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

Self

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/docscribe/plugin.rb', line 105

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

.process_plugin_insertions(results, entry, plugin) ⇒ Array<Hash<Symbol, Object>>

Merge plugin metadata into collector results and filter invalid ones.

Parameters:

  • results (Array<Hash<Symbol, Object>>) —

    collector plugin results to process

  • entry (Docscribe::Plugin::Registry::Entry) —

    registry entry with priority and order metadata

  • plugin (Object) —

    the collector plugin instance

Returns:

  • (Array<Hash<Symbol, Object>>) 


78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/docscribe/plugin.rb', line 78

def self.process_plugin_insertions(results, entry, plugin)
  results.map do |insertion|
    next nil unless valid_plugin_result?(insertion, plugin)

    insertion.merge(
      __docscribe_priority: entry.priority,
      __docscribe_plugin_class: plugin.class.name,
      __docscribe_plugin_order: entry.order
    )
  end.compact
end

.process_single_plugin_result(entry, ast, buffer) ⇒ Array<Hash<Symbol, Object>>, Array

Process a single collector plugin’s result.

Merges plugin metadata into each hash insertion and handles errors.

Parameters:

  • entry (Docscribe::Plugin::Registry::Entry) —

    registry entry with priority and order metadata

  • ast (Parser::AST::Node) —

    parsed AST root node

  • buffer (Parser::Source::Buffer) —

    source buffer for AST

Returns:

  • (Array<Hash<Symbol, Object>>) —

    if StandardError

  • (Array) —

    if StandardError

Raises:

  • (StandardError) 


63
64
65
66
67
68
69
70
 
# File 'lib/docscribe/plugin.rb', line 63

def self.process_single_plugin_result(entry, ast, buffer)
  plugin = entry.plugin
  results = Array(plugin.collect(ast, buffer))
  process_plugin_insertions(results, entry, plugin)
rescue StandardError => e
  warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
  []
end

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

Run all registered CollectorPlugins for one file’s AST.

Parameters:

  • ast (Parser::AST::Node) —

    parsed AST root node

  • buffer (Parser::Source::Buffer) —

    source buffer for AST

Returns:

  • (Array<Hash<Symbol, Object>>) 


49
50
51
 
# File 'lib/docscribe/plugin.rb', line 49

def self.run_collector_plugins(ast, buffer)
  Registry.collector_entries.flat_map { |entry| process_single_plugin_result(entry, ast, buffer) }
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

.valid_plugin_result?(insertion, plugin) ⇒ Boolean

Validate a CollectorPlugin result is a Hash.

Parameters:

  • insertion (Object) —

    collector plugin result

  • plugin (Object) —

    the collector plugin instance

Returns:

  • (Boolean) 


95
96
97
98
99
100
 
# File 'lib/docscribe/plugin.rb', line 95

def self.valid_plugin_result?(insertion, plugin)
  return true if insertion.is_a?(Hash)

  warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
  false
end