self_doc¶ ↑

• github.com/arnonmoscona/self_doc

Warning¶ ↑

• This is very experimental

• Not ready for anyone to use yet!!!

DESCRIPTION:¶ ↑

SelfDocumentaion is a simple DSL for supporting self documenting classes. Why do we need something other than RDoc? For the same reason that rake tasks can be self describing using the describe method. RDoc “lives” with the code and generate documentation for browsing. SelfDocumentaion generates documentation that “lives” inside the run-time code and can then be rendered at run time. In our particular situation at FanSnap.com, we have many back-end jobs that are generally launched using a rake based facility. We want to be able to document the different options available for a job much like rake --describe would do for rake tasks. SelfDocumentaion was created to satisfy this need.

This DSL is a bit more elaborate than what rake provides with describe and very superficially resembles Markaby or Parkaby.

The initial version of SelfDocumentaion only renders the documentation for terminal output. Later versions may add HTML support.

FEATURES/PROBLEMS:¶ ↑

• This is the first DSL version

• Has plain text rendering

• Does not have HTML rendering yet

SYNOPSIS:¶ ↑

Writing documentation (example):

gem 'self_doc'

class MyClass
  include SelfDoc

  documentation do
    h1 "constructor parameters"
    text "The constructor takes one argument and an options hash." 
    describe_method :new
    argument :mode, "which mode to run in. Allowed values:"
      optional
      default :new
      ul
        li ":new - does the new thing"
        li ":old - does the old thing"
    options_hash
      key :debug, "turns debug on"
        default false
      key :verbose
      key :default_value, "duh..."
    block "lets you do the real work"
  end

  def initialize(mode, opt={})
    #...
  end
end

• Note that this does not require any blocks (except for the outermost one) so as to keep the text as English-like as possible.

• You may use any number of documentation “sections” in your code, they will basically appens to a class variable that holds an ordered list of sections. The rendering methods allow you to render the first section, all of them or any range of sections.

Documentation methods:

• documentation starts a new documentation section. At least one is required to do anything. Until a new call is made - all the other methods will operate in the context of the latest section to be started. During this block all the documentation calls override whatever you may have defined by temporarily aliasing existing methods. Once the block exits then any methods previously defined are restored.

• h1 creates a “header level” text that will be emphasized in some way (depending on the formatter use)

• text takes a single text string as a parameter. Multiple consecutive are considered part of the same paragraph. If called with no argument this is taken as paragraph termination. The text method may be called in the context of any part of the documentation and the content will will be generally aligned (as best achieved) with the associated (parent) node.

• ul and ol start a bullet list or an ordered list respectively, and can be called in any context that text can be called in.

• li a list item. Takes one parameter that is the content of the list item

• describe_method takes exactly one argument and starts a method documentation sub-section, setting the context to all that follows until the next describe_method or documentation call.

• argument may only be called in the context of a method (demarcated by describe_method). The first argument is required and is the argument name (Symbol or String). A second description argument is optional. You may not call this method in the same method context after calling options_hash

• optional may be called in the context of an argument or an options hahs key. Denotes the argument as an optional argument.

• default also may be called in the context of an argument or an doptions hash key. Takes one argument that may be a String, a Symbol, nil, true, or false. Anything else will have to_s called on it.

• options_hash may only be called as the last argument of a method context (except for a possible block to follow), and sets the context for key calls

• key may be called in the context of a an options_hash. Takes at least the key name as a Symbol or String and optionally a description of the key

• block may be calles as the last call in the context of a describe_method to describe the blockl the method takes

Printing Documentation:

puts MyClass.render_documentation # => prints the documentation in the default format (:text)
puts MyClass.render_documentation(:format=>:plain) # => prints the documentation in the text format
puts MyClass.render_documentation(:section=>:first) # => prints only the first section of the documentation
puts MyClass.render_documentation(:section=>:all) # => same as puts MyClass.documentation
puts MyClass.render_documentation(:section=>[0,1,5]) # => prints the specified sections (zero based). Silently ignores sections that do not exist.

REQUIREMENTS:¶ ↑

• RSpec >= 1.2.7

• RDoc

INSTALL:¶ ↑

sudo gem install self_doc

LICENSE:¶ ↑

(The MIT License)

Copyright © 2009 Arnon Moscona

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.