= Lazydoc[http://tap.rubyforge.org/lazydoc]

Lazydoc lazily pulls documentation out of source files and makes it
available in code through lazy attributes.  Lazydoc is used by the
Tap[http://tap.rubyforge.org] framework.

== Description

Lazydoc can find two types of documentation: constant attributes and 
code comments.  To illustrate, consider the following:

  # Sample::key <value>
  # This is the comment content.  A content
  # string can span multiple lines...
  #
  #   code.is_allowed
  #   much.as_in RDoc
  #
  # and stops at the next non-comment
  # line, the next constant attribute,
  # or an end key
  class Sample
    extend Lazydoc::Attributes
    self.source_file = __FILE__

    lazy_attr :key

    # comment content for a code comment
    # may similarly span multiple lines
    def method_one
    end
  end

When a lazy attribute is called, Lazydoc scans <tt>source_file</tt> for
the corresponding constant attribute and makes it available as a
Lazydoc::Comment.

  comment = Sample::key
  comment.value       
  # => "<value>"

  comment.content       
  # => [
  # ["This is the comment content.  A content", "string can span multiple lines..."],
  # [""],
  # ["  code.is_allowed"],
  # ["  much.as_in RDoc"],
  # [""],
  # ["and stops at the next non-comment", "line, the next constant attribute,", "or an end key"]]

  "\n#{'.' * 30}\n" + comment.wrap(30) + "\n#{'.' * 30}\n"
  # => %q{
  # ..............................
  # This is the comment content.
  # A content string can span
  # multiple lines...
  # 
  #   code.is_allowed
  #   much.as_in RDoc
  # 
  # and stops at the next
  # non-comment line, the next
  # constant attribute, or an end
  # key
  # ..............................
  #}

In addition, individual lines of code may be registered and resolved by Lazydoc:

  doc = Sample.lazydoc.reset
  comment = doc.register(/method_one/)
  
  doc.resolve
  comment.subject       # => "  def method_one"
  comment.content       # => [["comment content for a code comment", "may similarly span multiple lines"]]

Check out these links for development, and bug tracking.

* Website[http://tap.rubyforge.org/lazydoc]
* Github[http://github.com/bahuvrihi/lazydoc/tree/master]
* {Google Group}[http://groups.google.com/group/ruby-on-tap]

== Usage

=== Constant Attributes

Constant attributes are like constants in Ruby, but with an extra 'key' 
that must consist of only lowercase letters and/or underscores.  For 
example, these are constant attributes:

  # Const::Name::key
  # Const::Name::key_with_underscores
  # ::key

While these are not:

  # Const::Name::Key
  # Const::Name::key2
  # Const::Name::k@y

Lazydoc parses a Lazydoc::Comment for each constant attribute by using the 
remainder of the line as a value (ie subject) and scanning down for content.
Scanning continues until a non-comment line, an end key, or a new attribute
is reached; the comment is then stored by constant name and key.

  str = %Q{
  # Const::Name::key value for key
  # comment for key
  # parsed until a 
  # non-comment line

  # Const::Name::another value for another
  # comment for another
  # parsed to an end key
  # Const::Name::another-
  #
  # ignored comment
  }

  doc = Lazydoc::Document.new
  doc.resolve(str)

  doc.to_hash {|comment| [comment.value, comment.to_s] } 
  # => {
  # 'Const::Name' => {
  #   'key' =>     ['value for key', 'comment for key parsed until a non-comment line'],
  #   'another' => ['value for another', 'comment for another parsed to an end key']}
  # }

Constant attributes are only parsed from commented lines.  To turn off
attribute parsing for a section of documentation, use start/stop keys:

  str = %Q{
  Const::Name::not_parsed

  # :::-
  # Const::Name::not_parsed
  # :::+
  # Const::Name::parsed value
  }

  doc = Lazydoc::Document.new
  doc.resolve(str)
  doc.to_hash {|comment| comment.value }   # => {'Const::Name' => {'parsed' => 'value'}}

To hide attributes from RDoc, make use of the RDoc <tt>:startdoc:</tt> 
document modifier like this (note that spaces are added to prevent RDoc
from hiding the example):

  # :start doc::Const::Name::one hidden in RDoc
  # * This line is visible in RDoc.
  # :start doc::Const::Name::one-
  # 
  #-- 
  # Const::Name::two
  # You can hide attribute comments like this.
  # Const::Name::two-
  #++
  #
  # * This line is also visible in RDoc.

As a side note, <tt>Const::Name::key</tt> is not a reference to the 'key' 
constant (as that would be invalid).  In *very* idiomatic ruby
<tt>Const::Name::key</tt> is equivalent to the method call 
<tt>Const::Name.key</tt>.

=== Code Comments

Code comments are lines registered for parsing if and when a Lazydoc gets 
resolved. Unlike constant attributes, the registered line is the comment
subject (ie value) and contents are parsed up from it (basically mimicking
the behavior of RDoc).

  str = %Q{
  # comment lines for
  # the method
  def method
  end

  # as in RDoc, the comment can be
  # separated from the method

  def another_method
  end
  }

  doc = Lazydoc::Document.new
  doc.register(3)
  doc.register(9)
  doc.resolve(str)

  doc.comments.collect {|comment| [comment.subject, comment.to_s] } 
  # => [
  # ['def method', 'comment lines for the method'],
  # ['def another_method', 'as in RDoc, the comment can be separated from the method']]

Comments may be registered to specific line numbers, or with a Proc or
Regexp that will determine the line number during resolution.  In the case
of a Regexp, the first matching line is used; Procs receive an array of
lines and should return the line number that should be used.  See 
Lazydoc::Comment#resolve for more details.

== Installation

Lazydoc is available as a gem on RubyForge[http://rubyforge.org/projects/tap].  Use:

  % gem install lazydoc

== Info 

Copyright (c) 2008, Regents of the University of Colorado.
Developer:: {Simon Chiang}[http://bahuvrihi.wordpress.com], {Biomolecular Structure Program}[http://biomol.uchsc.edu/], {Hansen Lab}[http://hsc-proteomics.uchsc.edu/hansenlab/] 
Support:: CU Denver School of Medicine Deans Academic Enrichment Fund
Licence:: {MIT-Style}[link:files/MIT-LICENSE.html]