rubydex 0.2.6 → 0.2.7

data/ext/rubydex/graph.c

@@ -8,6 +8,11 @@
 #include "rustbindings.h"
 #include "utils.h"
 
+/*
+ * RDoc parser workaround for https://github.com/ruby/rdoc/issues/1744:
+ * mRubydex = rb_define_module("Rubydex")
+ */
+
 static VALUE cGraph;
 static VALUE mRubydex;
 static VALUE cKeyword;
@@ -68,8 +73,12 @@ static VALUE rdxr_graph_alloc(VALUE klass) {
     return TypedData_Wrap_Struct(klass, &graph_type, graph);
 }
 
-// Graph#index_all: (Array[String] file_paths) -> Array[String]
-// Returns an array of IO error messages encountered during indexing
+/*
+ * call-seq:
+ *   index_all(file_paths) -> Array[String]
+ *
+ * Returns an array of I/O error messages encountered during indexing.
+ */
 static VALUE rdxr_graph_index_all(VALUE self, VALUE file_paths) {
     rdxi_check_array_of_strings(file_paths);
 
@@ -99,9 +108,12 @@ static VALUE rdxr_graph_index_all(VALUE self, VALUE file_paths) {
     return array;
 }
 
-// Indexes a single source string in memory, dispatching to the appropriate indexer based on language_id
-//
-// Graph#index_source: (String uri, String source, String language_id) -> void
+/*
+ * call-seq:
+ *   index_source(uri, source, language_id) -> nil
+ *
+ * Indexes a single source string in memory, dispatching to the appropriate indexer based on language_id.
+ */
 static VALUE rdxr_graph_index_source(VALUE self, VALUE uri, VALUE source, VALUE language_id) {
     Check_Type(uri, T_STRING);
     Check_Type(source, T_STRING);
@@ -148,8 +160,12 @@ static VALUE graph_declarations_size(VALUE self, VALUE _args, VALUE _eobj) {
     return SIZET2NUM(len);
 }
 
-// Graph#declarations: () -> Enumerator[Declaration]
-// Returns an enumerator that yields all declarations lazily
+/*
+ * call-seq:
+ *   declarations -> Enumerator[Rubydex::Declaration]
+ *
+ * Returns an enumerator that yields all declarations lazily.
+ */
 static VALUE rdxr_graph_declarations(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("declarations"), 0, NULL, graph_declarations_size);
@@ -178,8 +194,12 @@ static VALUE rdxr_graph_yield_search_results(VALUE self, void *iter) {
     return self;
 }
 
-// Graph#search: (String query) -> Enumerator[Declaration]
-// Returns an enumerator that yields declarations matching the query exactly (substring match)
+/*
+ * call-seq:
+ *   search(query) -> Enumerator[Rubydex::Declaration]
+ *
+ * Returns an enumerator that yields declarations matching the query exactly by substring.
+ */
 static VALUE rdxr_graph_search(VALUE self, VALUE query) {
     Check_Type(query, T_STRING);
 
@@ -193,8 +213,12 @@ static VALUE rdxr_graph_search(VALUE self, VALUE query) {
     return rdxr_graph_yield_search_results(self, rdx_graph_declarations_search(graph, StringValueCStr(query)));
 }
 
-// Graph#fuzzy_search: (String query) -> Enumerator[Declaration]
-// Returns an enumerator that yields declarations matching the query fuzzily
+/*
+ * call-seq:
+ *   fuzzy_search(query) -> Enumerator[Rubydex::Declaration]
+ *
+ * Returns an enumerator that yields declarations matching the query fuzzily.
+ */
 static VALUE rdxr_graph_fuzzy_search(VALUE self, VALUE query) {
     Check_Type(query, T_STRING);
 
@@ -243,8 +267,12 @@ static VALUE graph_documents_size(VALUE self, VALUE _args, VALUE _eobj) {
     return SIZET2NUM(len);
 }
 
-// Graph#documents: () -> Enumerator[Document]
-// Returns an enumerator that yields all documents lazily
+/*
+ * call-seq:
+ *   documents -> Enumerator[Rubydex::Document]
+ *
+ * Returns an enumerator that yields all documents lazily.
+ */
 static VALUE rdxr_graph_documents(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("documents"), 0, NULL, graph_documents_size);
@@ -260,8 +288,12 @@ static VALUE rdxr_graph_documents(VALUE self) {
     return self;
 }
 
-// Graph#[]: (String fully_qualified_name) -> Declaration
-// Returns a declaration handle for the given ID
+/*
+ * call-seq:
+ *   graph[fully_qualified_name] -> Rubydex::Declaration?
+ *
+ * Returns the declaration for the fully qualified name, or nil when no declaration exists.
+ */
 static VALUE rdxr_graph_aref(VALUE self, VALUE key) {
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
@@ -294,8 +326,12 @@ static VALUE graph_constant_references_size(VALUE self, VALUE _args, VALUE _eobj
     return SIZET2NUM(len);
 }
 
-// Graph#constant_references: () -> Enumerator[ConstantReference]
-// Returns an enumerator that yields constant references lazily
+/*
+ * call-seq:
+ *   constant_references -> Enumerator[Rubydex::ConstantReference]
+ *
+ * Returns an enumerator that yields constant references lazily.
+ */
 static VALUE rdxr_graph_constant_references(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("constant_references"), 0, NULL,
@@ -324,8 +360,12 @@ static VALUE graph_method_references_size(VALUE self, VALUE _args, VALUE _eobj)
     return SIZET2NUM(len);
 }
 
-// Graph#method_references: () -> Enumerator[MethodReference]
-// Returns an enumerator that yields method references lazily
+/*
+ * call-seq:
+ *   method_references -> Enumerator[Rubydex::MethodReference]
+ *
+ * Returns an enumerator that yields method references lazily.
+ */
 static VALUE rdxr_graph_method_references(VALUE self) {
     if (!rb_block_given_p()) {
         return rb_enumeratorize_with_size(self, rb_str_new2("method_references"), 0, NULL,
@@ -342,8 +382,12 @@ static VALUE rdxr_graph_method_references(VALUE self) {
     return self;
 }
 
-// Graph#document: (String uri) -> Document?
-// Returns the Document for the given URI, or nil if it doesn't exist.
+/*
+ * call-seq:
+ *   document(uri) -> Rubydex::Document?
+ *
+ * Returns the document for the URI, or nil if it does not exist.
+ */
 static VALUE rdxr_graph_document(VALUE self, VALUE uri) {
     Check_Type(uri, T_STRING);
 
@@ -360,9 +404,13 @@ static VALUE rdxr_graph_document(VALUE self, VALUE uri) {
     return rb_class_new_instance(2, argv, cDocument);
 }
 
-// Graph#delete_document: (String uri) -> Document?
-// Deletes a document and all of its definitions from the graph.
-// Returns the removed Document or nil if it doesn't exist.
+/*
+ * call-seq:
+ *   delete_document(uri) -> Rubydex::Document?
+ *
+ * Deletes a document and all of its definitions from the graph. Returns the removed document, or nil if it does not
+ * exist.
+ */
 static VALUE rdxr_graph_delete_document(VALUE self, VALUE uri) {
     Check_Type(uri, T_STRING);
 
@@ -379,8 +427,12 @@ static VALUE rdxr_graph_delete_document(VALUE self, VALUE uri) {
     return rb_class_new_instance(2, argv, cDocument);
 }
 
-// Graph#resolve: () -> self
-// Runs the resolver to compute declarations and ownership
+/*
+ * call-seq:
+ *   resolve -> self
+ *
+ * Runs the resolver to compute declarations and ownership.
+ */
 static VALUE rdxr_graph_resolve(VALUE self) {
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
@@ -388,8 +440,12 @@ static VALUE rdxr_graph_resolve(VALUE self) {
     return self;
 }
 
-// Graph#encoding=: (String) -> void
-// Sets the encoding used for transforming byte offsets into LSP code unit line/column positions
+/*
+ * call-seq:
+ *   encoding=(encoding) -> nil
+ *
+ * Sets the encoding used for transforming byte offsets into LSP code unit line and column positions.
+ */
 static VALUE rdxr_graph_set_encoding(VALUE self, VALUE encoding) {
     Check_Type(encoding, T_STRING);
 
@@ -404,8 +460,12 @@ static VALUE rdxr_graph_set_encoding(VALUE self, VALUE encoding) {
     return Qnil;
 }
 
-// Graph#resolve_constant: (String, Array[String]) -> Declaration?
-// Runs the resolver on a single constant reference to determine what it points to
+/*
+ * call-seq:
+ *   resolve_constant(name, nesting) -> Rubydex::Declaration?
+ *
+ * Runs the resolver on a single constant reference to determine what it points to.
+ */
 static VALUE rdxr_graph_resolve_constant(VALUE self, VALUE const_name, VALUE nesting) {
     Check_Type(const_name, T_STRING);
     rdxi_check_array_of_strings(nesting);
@@ -433,8 +493,12 @@ static VALUE rdxr_graph_resolve_constant(VALUE self, VALUE const_name, VALUE nes
     return rb_class_new_instance(2, argv, decl_class);
 }
 
-// Graph#resolve_require_path: (String require_path, Array[String] load_paths) -> Document?
-// Resolves a require path to its Document.
+/*
+ * call-seq:
+ *   resolve_require_path(require_path, load_paths) -> Rubydex::Document?
+ *
+ * Resolves a require path to its document.
+ */
 static VALUE rdxr_graph_resolve_require_path(VALUE self, VALUE require_path, VALUE load_paths) {
     Check_Type(require_path, T_STRING);
     rdxi_check_array_of_strings(load_paths);
@@ -459,8 +523,12 @@ static VALUE rdxr_graph_resolve_require_path(VALUE self, VALUE require_path, VAL
     return rb_class_new_instance(2, argv, cDocument);
 }
 
-// Graph#require_paths: (Array[String] load_path) -> Array[String]
-// Returns all require paths for completion.
+/*
+ * call-seq:
+ *   require_paths(load_paths) -> Array[String]
+ *
+ * Returns all require paths for completion.
+ */
 static VALUE rdxr_graph_require_paths(VALUE self, VALUE load_path) {
     rdxi_check_array_of_strings(load_path);
 
@@ -488,8 +556,12 @@ static VALUE rdxr_graph_require_paths(VALUE self, VALUE load_path) {
     return array;
 }
 
-// Graph#check_integrity: () -> Array[Rubydex::IntegrityFailure]
-// Returns an array of IntegrityFailure objects, empty if no issues found
+/*
+ * call-seq:
+ *   check_integrity -> Array[Rubydex::IntegrityFailure]
+ *
+ * Returns an array of integrity failures, or an empty array if no issues were found.
+ */
 static VALUE rdxr_graph_check_integrity(VALUE self) {
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
@@ -514,7 +586,12 @@ static VALUE rdxr_graph_check_integrity(VALUE self) {
     return array;
 }
 
-// Graph#diagnostics -> Array[Rubydex::Diagnostic]
+/*
+ * call-seq:
+ *   diagnostics -> Array[Rubydex::Diagnostic]
+ *
+ * Returns diagnostics emitted while indexing or resolving the graph.
+ */
 static VALUE rdxr_graph_diagnostics(VALUE self) {
     void *graph;
     TypedData_Get_Struct(self, void *, &graph_type, graph);
@@ -531,7 +608,7 @@ static VALUE rdxr_graph_diagnostics(VALUE self) {
     for (size_t i = 0; i < array->len; i++) {
         DiagnosticEntry entry = array->items[i];
         VALUE message = entry.message == NULL ? Qnil : rb_utf8_str_new_cstr(entry.message);
-        VALUE rule = rb_str_new2(entry.rule);
+        VALUE rule = rb_str_intern(rb_str_new2(entry.rule));
         VALUE location = rdxi_build_location_value(entry.location);
 
         VALUE kwargs = rb_hash_new();
@@ -603,10 +680,13 @@ static VALUE completion_result_to_ruby_array(struct CompletionResult result, VAL
     return ruby_array;
 }
 
-// Graph#complete_expression: (Array[String] nesting, self_receiver:) -> Array[Declaration | Keyword]
-// Returns completion candidates for an expression context.
-// The nesting array represents the lexical scope stack. The required self_receiver keyword argument overrides the
-// self-type (e.g., "Foo::<Foo>" for `def Foo.bar`); when nil, self is derived from the innermost nesting element.
+/*
+ * call-seq:
+ *   complete_expression(nesting, self_receiver:) -> Array[Rubydex::Declaration | Rubydex::Keyword]
+ *
+ * Returns completion candidates for an expression context. The nesting array represents the lexical scope stack. The
+ * required self_receiver keyword argument overrides the self type; pass nil when the self type is unknown.
+ */
 static VALUE rdxr_graph_complete_expression(int argc, VALUE *argv, VALUE self) {
     VALUE nesting, opts;
     rb_scan_args(argc, argv, "1:", &nesting, &opts);
@@ -627,11 +707,13 @@ static VALUE rdxr_graph_complete_expression(int argc, VALUE *argv, VALUE self) {
     return completion_result_to_ruby_array(result, self);
 }
 
-// Graph#complete_namespace_access: (String name, self_receiver:) -> Array[Declaration]
-// Returns completion candidates after a namespace access operator (e.g., `Foo::`).
-// The required self_receiver kwarg is the caller's runtime self type, used to filter
-// visibility-restricted singleton methods (e.g., `private_class_method`). Pass `nil` when there
-// is no caller context.
+/*
+ * call-seq:
+ *   complete_namespace_access(name, self_receiver:) -> Array[Rubydex::Declaration]
+ *
+ * Returns completion candidates after a namespace access operator such as Foo::. The required self_receiver keyword
+ * argument is the caller's runtime self type; pass nil when there is no caller context.
+ */
 static VALUE rdxr_graph_complete_namespace_access(int argc, VALUE *argv, VALUE self) {
     VALUE name, opts;
     rb_scan_args(argc, argv, "1:", &name, &opts);
@@ -647,10 +729,13 @@ static VALUE rdxr_graph_complete_namespace_access(int argc, VALUE *argv, VALUE s
     return completion_result_to_ruby_array(result, self);
 }
 
-// Graph#complete_method_call: (String name, self_receiver:) -> Array[Declaration]
-// Returns completion candidates after a method call operator (e.g., `foo.`).
-// The required self_receiver kwarg is the caller's runtime self type, used for visibility checks (private/protected).
-// Pass `nil` when there is no caller context.
+/*
+ * call-seq:
+ *   complete_method_call(name, self_receiver:) -> Array[Rubydex::Method]
+ *
+ * Returns completion candidates after a method call operator such as foo. The required self_receiver keyword argument
+ * is the caller's runtime self type; pass nil when there is no caller context.
+ */
 static VALUE rdxr_graph_complete_method_call(int argc, VALUE *argv, VALUE self) {
     VALUE name, opts;
     rb_scan_args(argc, argv, "1:", &name, &opts);
@@ -666,9 +751,13 @@ static VALUE rdxr_graph_complete_method_call(int argc, VALUE *argv, VALUE self)
     return completion_result_to_ruby_array(result, self);
 }
 
-// Graph#complete_method_argument: (String name, Array[String] nesting, self_receiver:) -> Array[Declaration | Keyword | KeywordParameter]
-// Returns completion candidates inside a method call's argument list (e.g., `foo.bar(|)`).
-// See complete_expression for semantics of self_receiver (required, may be nil).
+/*
+ * call-seq:
+ *   complete_method_argument(name, nesting, self_receiver:) -> Array[Rubydex::Declaration | Rubydex::Keyword | Rubydex::KeywordParameter]
+ *
+ * Returns completion candidates inside a method call's argument list. See complete_expression for self_receiver
+ * semantics.
+ */
 static VALUE rdxr_graph_complete_method_argument(int argc, VALUE *argv, VALUE self) {
     VALUE name, nesting, opts;
     rb_scan_args(argc, argv, "2:", &name, &nesting, &opts);
@@ -691,8 +780,12 @@ static VALUE rdxr_graph_complete_method_argument(int argc, VALUE *argv, VALUE se
     return completion_result_to_ruby_array(result, self);
 }
 
-// Graph#exclude_paths: (Array[String] paths) -> void
-// Excludes the given paths from file discovery during indexing.
+/*
+ * call-seq:
+ *   exclude_paths(paths) -> nil
+ *
+ * Excludes the paths from file discovery during indexing.
+ */
 static VALUE rdxr_graph_exclude_paths(VALUE self, VALUE paths) {
     Check_Type(paths, T_ARRAY);
     rdxi_check_array_of_strings(paths);
@@ -709,8 +802,12 @@ static VALUE rdxr_graph_exclude_paths(VALUE self, VALUE paths) {
     return Qnil;
 }
 
-// Graph#excluded_paths: () -> Array[String]
-// Returns the list of paths currently excluded from file discovery.
+/*
+ * call-seq:
+ *   excluded_paths -> Array[String]
+ *
+ * Returns the paths currently excluded from file discovery.
+ */
 static VALUE rdxr_graph_excluded_paths(VALUE self) {
     void *graph;
     TypedData_Get_Struct(self, void*, &graph_type, graph);
@@ -731,8 +828,81 @@ static VALUE rdxr_graph_excluded_paths(VALUE self) {
     return array;
 }
 
-// Graph#keyword: (String name) -> Keyword?
-// Returns a Keyword object for the given keyword name, or nil if it is not a keyword.
+/*
+ * call-seq:
+ *   workspace_path -> String
+ *
+ * Returns the root directory of the workspace being indexed.
+ */
+static VALUE rdxr_graph_workspace_path(VALUE self) {
+    void *graph;
+    TypedData_Get_Struct(self, void*, &graph_type, graph);
+
+    const char *result = rdx_graph_workspace_path(graph);
+    if (result == NULL) {
+        rb_raise(rb_eRuntimeError, "Converting workspace path to Ruby string failed");
+    }
+
+    VALUE path = rdxi_owned_c_string_to_ruby(result);
+    return path;
+}
+
+/*
+ * call-seq:
+ *   workspace_path=(path) -> void
+ *
+ * Sets the root directory of the workspace being indexed.
+ */
+static VALUE rdxr_graph_set_workspace_path(VALUE self, VALUE path) {
+    Check_Type(path, T_STRING);
+
+    void *graph;
+    TypedData_Get_Struct(self, void*, &graph_type, graph);
+
+    rdx_graph_set_workspace_path(graph, StringValueCStr(path));
+    return path;
+}
+
+/*
+ * call-seq:
+ *   load_config(config_path = nil) -> void
+ *
+ * Loads a configuration file for the graph. If `config_path` is nil, loads the default configuration file at
+ * `workspace_path/rubydex.toml` if it exists. Will raise on malformed files or if an explicit path is given but the
+ * file does not exist.
+ */
+static VALUE rdxr_graph_load_config(int argc, VALUE *argv, VALUE self) {
+    VALUE config_path;
+    rb_scan_args(argc, argv, "01", &config_path);
+
+    void *graph;
+    TypedData_Get_Struct(self, void *, &graph_type, graph);
+
+    const char *config_path_cstr = NULL;
+
+    if (!NIL_P(config_path)) {
+        Check_Type(config_path, T_STRING);
+        config_path_cstr = StringValueCStr(config_path);
+    }
+
+    const char *error = rdx_graph_load_config(graph, config_path_cstr);
+    if (error == NULL) {
+        return Qnil;
+    }
+
+    VALUE message = rb_utf8_str_new_cstr(error);
+    free_c_string(error);
+
+    VALUE config_error = rb_const_get(mRubydex, rb_intern("ConfigError"));
+    rb_exc_raise(rb_exc_new_str(config_error, message));
+}
+
+/*
+ * call-seq:
+ *   keyword(name) -> Rubydex::Keyword?
+ *
+ * Returns the keyword object for the name, or nil if it is not a Ruby keyword.
+ */
 static VALUE rdxr_graph_keyword(VALUE self, VALUE name) {
     Check_Type(name, T_STRING);
 
@@ -783,5 +953,8 @@ void rdxi_initialize_graph(VALUE moduleRubydex) {
     rb_define_method(cGraph, "complete_method_argument", rdxr_graph_complete_method_argument, -1);
     rb_define_method(cGraph, "exclude_paths", rdxr_graph_exclude_paths, 1);
     rb_define_method(cGraph, "excluded_paths", rdxr_graph_excluded_paths, 0);
+    rb_define_method(cGraph, "workspace_path", rdxr_graph_workspace_path, 0);
+    rb_define_method(cGraph, "workspace_path=", rdxr_graph_set_workspace_path, 1);
+    rb_define_method(cGraph, "load_config", rdxr_graph_load_config, -1);
     rb_define_method(cGraph, "keyword", rdxr_graph_keyword, 1);
 }

data/ext/rubydex/handle.h

@@ -1,6 +1,7 @@
 #ifndef RUBYDEX_HANDLE_H
 #define RUBYDEX_HANDLE_H
 
+#include "graph.h"
 #include "ruby.h"
 
 typedef struct {
@@ -34,6 +35,18 @@ static const rb_data_type_t handle_type = {
     .flags = RUBY_TYPED_FREE_IMMEDIATELY,
 };
 
+static inline void *rdxi_graph_from_handle(VALUE self, HandleData **out_data) {
+    HandleData *data;
+    TypedData_Get_Struct(self, HandleData, &handle_type, data);
+
+    void *graph;
+    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+
+    *out_data = data;
+
+    return graph;
+}
+
 static VALUE rdxr_handle_alloc(VALUE klass) {
     HandleData *data = ALLOC(HandleData);
 

data/ext/rubydex/location.c

@@ -1,5 +1,10 @@
 #include "location.h"
 
+/*
+ * RDoc parser workaround for https://github.com/ruby/rdoc/issues/1744:
+ * mRubydex = rb_define_module("Rubydex")
+ */
+
 VALUE cLocation;
 
 VALUE rdxi_build_location_value(Location *loc) {

data/ext/rubydex/reference.c

@@ -4,6 +4,12 @@
 #include "handle.h"
 #include "location.h"
 #include "rustbindings.h"
+#include "utils.h"
+
+/*
+ * RDoc parser workaround for https://github.com/ruby/rdoc/issues/1744:
+ * mRubydex = rb_define_module("Rubydex")
+ */
 
 VALUE cReference;
 VALUE cConstantReference;
@@ -11,31 +17,29 @@ VALUE cUnresolvedConstantReference;
 VALUE cResolvedConstantReference;
 VALUE cMethodReference;
 
-// ConstantReference#name -> String
+/*
+ * call-seq:
+ *   name -> String
+ *
+ * Returns the unresolved constant name.
+ */
 static VALUE rdxr_constant_reference_name(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const char *name = rdx_constant_reference_name(graph, data->id);
-    if (name == NULL) {
-        return Qnil;
-    }
-
-    VALUE str = rb_utf8_str_new_cstr(name);
-    free_c_string(name);
-    return str;
+    return rdxi_owned_c_string_to_ruby(name);
 }
 
-// ConstantReference#location -> Rubydex::Location
+/*
+ * call-seq:
+ *   location -> Rubydex::Location
+ *
+ * Returns the source location for this constant reference.
+ */
 static VALUE rdxr_constant_reference_location(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_constant_reference_location(graph, data->id);
     VALUE location = rdxi_build_location_value(loc);
@@ -43,31 +47,29 @@ static VALUE rdxr_constant_reference_location(VALUE self) {
     return location;
 }
 
-// MethodReference#name -> String
+/*
+ * call-seq:
+ *   name -> String
+ *
+ * Returns the referenced method name.
+ */
 static VALUE rdxr_method_reference_name(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const char *name = rdx_method_reference_name(graph, data->id);
-    if (name == NULL) {
-        return Qnil;
-    }
-
-    VALUE str = rb_utf8_str_new_cstr(name);
-    free_c_string(name);
-    return str;
+    return rdxi_owned_c_string_to_ruby(name);
 }
 
-// MethodReference#location -> Rubydex::Location
+/*
+ * call-seq:
+ *   location -> Rubydex::Location
+ *
+ * Returns the source location for this method reference.
+ */
 static VALUE rdxr_method_reference_location(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     Location *loc = rdx_method_reference_location(graph, data->id);
     VALUE location = rdxi_build_location_value(loc);
@@ -75,15 +77,16 @@ static VALUE rdxr_method_reference_location(VALUE self) {
     return location;
 }
 
-// MethodReference#receiver -> Rubydex::Declaration?
-// Returns the resolved declaration for the receiver of the method call. Returns nil when the receiver is not a
-// tracked constant or cannot be resolved.
+/*
+ * call-seq:
+ *   receiver -> Rubydex::Declaration?
+ *
+ * Returns the resolved declaration for the receiver of the method call. Returns nil when the receiver is not a tracked
+ * constant or cannot be resolved.
+ */
 static VALUE rdxr_method_reference_receiver(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const struct CDeclaration *decl = rdx_method_reference_receiver_declaration(graph, data->id);
     if (decl == NULL) {
@@ -97,13 +100,15 @@ static VALUE rdxr_method_reference_receiver(VALUE self) {
     return rb_class_new_instance(2, argv, decl_class);
 }
 
-// ResolvedConstantReference#declaration -> Declaration
+/*
+ * call-seq:
+ *   declaration -> Rubydex::Declaration
+ *
+ * Returns the resolved declaration.
+ */
 static VALUE rdxr_resolved_constant_reference_declaration(VALUE self) {
     HandleData *data;
-    TypedData_Get_Struct(self, HandleData, &handle_type, data);
-
-    void *graph;
-    TypedData_Get_Struct(data->graph_obj, void *, &graph_type, graph);
+    void *graph = rdxi_graph_from_handle(self, &data);
 
     const struct CDeclaration *decl = rdx_resolved_constant_reference_declaration(graph, data->id);
     if (decl == NULL) {

data/ext/rubydex/rubydex.c

@@ -12,6 +12,11 @@ VALUE mRubydex;
 void Init_rubydex(void) {
     rb_ext_ractor_safe(true);
 
+    /*
+     * Document-module: Rubydex
+     *
+     * Namespace for Rubydex's Ruby API.
+     */
     mRubydex = rb_define_module("Rubydex");
     rdxi_initialize_graph(mRubydex);
     rdxi_initialize_declaration(mRubydex);