Class: YARD::Tags::AppendixDirective

Inherits:
Directive
  • Object
show all
Defined in:
lib/yard-appendix/tags/appendix_directive.rb

Overview

Note:

When defining an appendix entry, there’s no need to prefix its name with ‘Appendix: ’ as that is automatically done for you.

Defines a @!appendix directive that allows writing Appendix entries which will be attached to the end of the namespace’s output, similar to appendixes in books or documents.

You can also reference the appendix identified by ‘Title` in other parts of your namespace documentation strings by using the @see tag. See the “See Also” link for more info about referencing appendices.

Examples:

Appendix definition syntax

module SomeModule
  # @!appendix Title
  #
  # Appendix body.
end

Defining an appendix titled ‘API Response Codes’


class BananaAPIController
  # Explain why one would want a fried banana, what it would do
  # to their health and self-esteem, and any side-effects one
  # would enjoy.
  #
  # @see Appendix: API Response Codes
  def serve_fried_bananas
  end

  # @!appendix API Response Codes
  #
  # The following map explains the HTTP response codes returned
  # by our servers and how you should treat them:
  #
  #   1. 200 -> a banana is available
  #   1. 403 -> that banana is super exclusive
  #   1. 404 -> no such banana, verify the ID
end

See Also:

Instance Method Summary collapse

Instance Method Details

#call ⇒ Object 



76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/yard-appendix/tags/appendix_directive.rb', line 76

def call
  # no resolver? then use the handler's namespace
  comment_ns = handler.namespace

  if resolver
    comment_ns = resolver.namespace_for(statement, namespace)
    log.debug "yard-appendix: appendix #{tag.name} will be enclosed under #{comment_ns}"
  end

  log.info "yard-appendix: appendix #{tag.name} has been registered under #{comment_ns.name}"
  appendix = CodeObjects::AppendixObject.new(comment_ns, tag.name)
  handler.register_docstring appendix, tag.text
  handler.register_file_info appendix
end

#namespace ⇒ Object 



73
 
# File 'lib/yard-appendix/tags/appendix_directive.rb', line 73

def namespace;    handler.namespace; end

#resolver ⇒ Object 



74
 
# File 'lib/yard-appendix/tags/appendix_directive.rb', line 74

def resolver;     handler.globals.resolver; end

#statement ⇒ Object 



72
 
# File 'lib/yard-appendix/tags/appendix_directive.rb', line 72

def statement;    handler.statement; end