This directory contains example plugins demonstrating the two extension points provided by Docscribe's plugin system.
| Type | Purpose |
|---|---|
| TagPlugin | Append extra YARD tags to already-collected methods |
| CollectorPlugin | Document non-standard DSL constructs by walking the AST directly |
tag_plugin/—ApiTagPlugin: appends@api public/@api privateto every method based on its Ruby visibility.
-
rails_associations/—RailsAssociations: documents ActiveRecord association macros (belongs_to,has_many,has_one,has_and_belongs_to_many). -
schema_attributes/—SchemaAttributes: generates@!attributeblocks with correct column types by parsingdb/schema.rb. -
model_attributes/—ModelAttributes: generates accurate@returntypes for ActiveRecord model methods by readingdb/schema.rbordb/structure.sql.
Use TagPlugin when you want to append one or more tags to methods that Docscribe already collects (def /
def self.). The plugin receives a snapshot of the method and returns Array<Docscribe::Plugin::Tag>.
Use CollectorPlugin when you need to document constructs that are not def nodes — DSL macros, define_method,
association helpers, and so on. The plugin receives the raw AST and source buffer and returns insertion targets
directly.
Note
A CollectorPlugin can target ordinary def methods to override the standard collector's output.
When a plugin and the standard collector both insert docs at the same source position, the plugin takes priority and
the standard collector's insertion is dropped.
If multiple CollectorPlugins target the same source position, Registry.register(plugin, priority: N) (default 0)
controls which one wins: the highest priority plugin(s) are kept (ties are kept).
- only the highest-priority plugin insertion(s) are kept (ties are kept)
- multiple insertions from the winning plugin(s) at that position are preserved (e.g.
SchemaAttributesmay generate several@!attributeblocks at one anchor point)
CollectorPlugins can return either doc: (raw string, replaces the standard output entirely) or method_override:
(structured data that patches @return, @param, and tags while keeping the standard DocBuilder pipeline).
Docscribe applies indentation automatically and may prepend the configured default method message for def/defs
anchors if the plugin output contains only tags.