selfdoc v0.15.1 /selfdoc.extractors.go
Updated
On this page

Go source extractor module that uses regex-based parsing to extract exported functions, struct fields, and doc comments from .go files for directives.

#selfdoc.extractors.go

#selfdoc.extractors.go

Go source extractor -- resolves directives by extracting from .go files.

Uses regex-based parsing (no Go toolchain required). Handles:

  • :::module -- extract package doc, exported funcs/types/consts/vars
  • :::test -- extract test source code
  • :::schema -- extract struct fields as a table
  • :::cli -- extract usage constants and flag.* calls
  • :::config -- extract config file contents as tables (JSON/TOML/YAML)

#GoExtractor

Go language extractor implementing LanguageExtractor protocol.

#name

python
def name(self) -> str

#detect

python
def detect(self, dir_path: str) -> bool

#resolve_path

python
def resolve_path(self, path_arg: str, source_paths: list[str], base_dir: str) -> str | None

#extract

python
def extract(self, directive_name: str, attrs: dict[str, str], body: list[str], source_paths: list[str], base_dir: str) -> str

#file_extensions

python
def file_extensions(self) -> list[str]

#public_symbols

python
def public_symbols(self, file_path: str) -> list[str]

Extract exported (capitalized) symbols from a Go source file.

Skips lines inside // and / / comments. Handles const (...) and var (...) blocks.

#_handle_module

python
def _handle_module(arg, body, source_paths, base_dir, attrs)

Extract package doc, exported funcs, types, consts, and vars.

arg is a package directory path (e.g. "internal/commit"). Finds all .go files in that directory (excluding _test.go), extracts the package doc comment and all exported declarations.

#_resolve_package_dir

python
def _resolve_package_dir(arg, source_paths, base_dir)

Resolve a package path argument to an actual directory.

Tries each source_path prefix, then the base_dir directly.

#_extract_package_doc

python
def _extract_package_doc(file_contents)

Extract the package name and doc comment from Go source files.

The package doc is the contiguous // comment block immediately above the package declaration. Returns (package_name, doc_string).

#_collect_comment_block_above

python
def _collect_comment_block_above(lines, target_line_idx)

Collect contiguous // comment lines immediately above target_line_idx.

Skips blank lines between the comment block and the declaration. Returns the comment text with // prefixes stripped.

#_extract_exported_declarations

python
def _extract_exported_declarations(source)

Extract all exported declarations from a Go source file.

Returns a list of dicts with keys: kind, name, signature, doc.

#_extract_const_block

python
def _extract_const_block(lines, block_start_idx, declarations, seen_names)

Extract exported constants from a const (...) block.

The doc comment for the entire block is attached to the first exported constant. Individual constants may also have their own // comments.

#_extract_var_block

python
def _extract_var_block(lines, block_start_idx, declarations, seen_names)

Extract exported variables from a var (...) block.

#_handle_test

python
def _handle_test(arg, body, source_paths, base_dir, attrs)

Extract test source code from a Go test file.

arg format: [TestFuncName]

#_resolve_file_path

python
def _resolve_file_path(file_path, source_paths, base_dir)

Resolve a file path relative to base_dir or source_paths.

#_extract_go_function

python
def _extract_go_function(source, func_name)

Extract a complete function from Go source by name.

Uses brace-counting to find the function body boundaries.

#_handle_schema

python
def _handle_schema(arg, body, source_paths, base_dir, attrs)

Extract struct type fields as a markdown table.

arg format: [TypeName] If TypeName is omitted, extracts the first exported struct found.

#_extract_structs

python
def _extract_structs(source)

Extract all exported struct type declarations from Go source.

Returns a list of dicts: {name, doc, fields: [{name, type, tag, comment}]}.

#_parse_struct_field

python
def _parse_struct_field(field_line, lines, line_idx)

Parse a single struct field line.

Returns {name, type, tag, comment} or None if not a field.

#_format_struct_table

python
def _format_struct_table(struct_info)

Format a struct's fields as a markdown table.

#_handle_cli

python
def _handle_cli(arg, body, source_paths, base_dir, attrs)

Extract CLI usage/help text and flag definitions from Go source.

Looks for:

  • String constants named usage, helpText, usageText (case-insensitive match)
  • flag.StringVar, flag.BoolVar, etc. calls
  • strictcli BoolFlag/StringFlag/Command calls

The arg can be a file path or a package directory path (like :::module). Resolves via _resolve_package_dir first, then _resolve_file_path as fallback.

#_extract_usage_constants

python
def _extract_usage_constants(source)

Find string constants/functions that return usage text.

Looks for patterns like:

  • const usage = ...
  • func usageText() string { return ... }
  • Any variable/const with "usage" or "help" in the name containing a string

#_extract_flag_calls

python
def _extract_flag_calls(source)

Extract flag.XxxVar and flag.Xxx calls from Go source.

Returns list of {name, type, default, desc}.

#_extract_strictcli_flags

python
def _extract_strictcli_flags(source)

Extract strictcli flag definitions from Go source.

Matches patterns like:

  • app.BoolFlag("name", "description")
  • app.StringFlag("name", "description")
  • cli.BoolFlag("name", "description")
  • .BoolFlag("name", "description")

Returns list of {name, type, default, desc}.

#_extract_strictcli_commands

python
def _extract_strictcli_commands(source)

Extract strictcli command definitions from Go source.

Matches patterns like:

  • app.Command("name", "description", ...)
  • cli.Command("name", "description", ...)

Returns list of {name, desc}.

#_handle_config

python
def _handle_config(arg, body, source_paths, base_dir, attrs)

Extract config file contents as a documented table.

Supports JSON and TOML. Detects format from file extension. Delegates to the same logic as the Python extractor.

#_handle_prose_desc

python
def _handle_prose_desc(arg, body, source_paths, base_dir, attrs)

Extract only the package doc comment as prose markdown.

Unlike :::module which also lists exported declarations, this directive returns just the package-level doc comment.