Module: Docscribe::Plugin

Defined in:
lib/docscribe/plugin.rb,
lib/docscribe/plugin/tag.rb,
lib/docscribe/plugin/context.rb,
lib/docscribe/plugin/registry.rb,
lib/docscribe/plugin/base/tag_plugin.rb,
lib/docscribe/plugin/base/collector_plugin.rb

Overview

Plugin system entry point.

Provides two extension points:

  1. TagPlugin — hooks into already-collected method insertions and appends additional YARD tags. Subclass Base::TagPlugin and override #call.

  2. CollectorPlugin — receives the raw AST and walks it independently. Used for non-standard structures that Docscribe’s Collector does not recognize. Subclass Base::CollectorPlugin and override #collect.

Defined Under Namespace

Modules: Base, Registry Classes: Context, Tag

Class Method Summary collapse

Class Method Details

.debug? ⇒ Boolean

Returns:

  • (Boolean) 


73
74
75
 
# File 'lib/docscribe/plugin.rb', line 73

def self.debug?
  ENV['DOCSCRIBE_DEBUG'] == '1'
end

.run_collector_plugins(ast, buffer) ⇒ Array<Hash>

Run all registered CollectorPlugins for one file’s AST.

Parameters:

  • ast (Parser::AST::Node)
  • buffer (Parser::Source::Buffer)

Returns:

  • (Array<Hash>)

Raises:

  • (StandardError) 


50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/docscribe/plugin.rb', line 50

def self.run_collector_plugins(ast, buffer)
  Registry.collector_entries.flat_map do |entry|
    plugin = entry.plugin

    Array(plugin.collect(ast, buffer)).map do |insertion|
      unless insertion.is_a?(Hash)
        warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
        next nil
      end

      insertion.merge(
        __docscribe_priority: entry.priority,
        __docscribe_plugin_class: plugin.class.name,
        __docscribe_plugin_order: entry.order
      )
    end.compact
  rescue StandardError => e
    warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
    []
  end
end

.run_tag_plugins(context) ⇒ Array<Docscribe::Plugin::Tag>

Run all registered TagPlugins for one method context.

Errors in individual plugins are caught so one broken plugin does not abort the entire run.

Parameters:

Returns:

Raises:

  • (StandardError) 


29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/docscribe/plugin.rb', line 29

def self.run_tag_plugins(context)
  Registry.tag_entries
          # Higher number => higher priority (run earlier).
          # This matters when multiple TagPlugins emit the same tag name
          # and Docscribe deduplicates tags by name.
          .sort_by { |entry| [-entry.priority, entry.order] }
          .flat_map do |entry|
    plugin = entry.plugin
    plugin.call(context)
  rescue StandardError => e
    warn "Docscribe: TagPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
    []
  end
end