Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
JavaScript inline documentation parser

Fix YAML parsing issue that emerged in Ruby 1.9.

In 1.8.7:

	irb(main):001:0> require 'yaml'
	=> true
	irb(main):007:0> YAML.load('foo: [?]')
	=> {"foo"=>["?"]}

In 1.9.3:

	irb(main):002:0> YAML.load('foo: [?]')
	Psych::SyntaxError: (<unknown>): did not find expected ',' or ']' while parsing a flow sequence at line 1 column 6
		from /Users/andrew.dupont/.rbenv/versions/1.9.3-p392/lib/ruby/1.9.1/psych.rb:203:in `parse'
		from /Users/andrew.dupont/.rbenv/versions/1.9.3-p392/lib/ruby/1.9.1/psych.rb:203:in `parse_stream'
		from /Users/andrew.dupont/.rbenv/versions/1.9.3-p392/lib/ruby/1.9.1/psych.rb:151:in `parse'
		from /Users/andrew.dupont/.rbenv/versions/1.9.3-p392/lib/ruby/1.9.1/psych.rb:127:in `load'
		from (irb):2
		from /Users/andrew.dupont/.rbenv/versions/1.9.3-p392/bin/irb:12:in `<main>'

In PDoc, `?` can be an argument type and a return type. When it's an argument type, we end up with `types: [?]` in the YAML file, and though that was OK before Psych existed, it's not OK now. This was preventing documentation from being generated from at least Ruby 1.9.3 onward.

The solution is to put quotes around the types so that YAML knows we mean for them to be strings.

This ends up not being a problem for the return type (`return_value` in the YAML) because it ends up being escaped, as are most of the values in the YAML output.
latest commit b8da8a0e3e
Andrew Dupont savetheclocktower authored savetheclocktower committed

README.markdown

PDoc

PDoc is an inline comment parser and JavaScript documentation generator written in Ruby. It is designed for documenting Prototype and Prototype-based libraries.

PDoc uses Treetop, a Ruby-based DSL for text parsing and interpretation, and its own ActionView-inspired, ERB-based templating system for HTML generation. Other documentation generators (e.g., DocBook XML) are planned.

Unlike other inline-doc parsers, PDoc does not rely on the JavaScript source code at all; it only parses the comments. This approach, though slightly more verbose, is much better at generating consistent, reliable documentation, and avoids the headaches encountered when documenting highly dynamic languages.

Installation

PDoc depends on Rake, your choice of markdown parser, and treetop, all of which can be obtained through RubyGems:

gem install rake bluecloth treetop

Usage

For hints on how to run PDoc on the command line, consult the built-in Rake tasks (in Rakefile) and the PDoc::Runner class (in lib/pdoc/runner.rb).

How it works

The process of turning inline PDoc comments into a human-friendly document has two phases.

Parsing phase

In this phase, the source files are scanned for PDoc comments, then parsed with the Ruby files generated from the Treetop language grammar. The product of this phase is a tree full of specialized classes, all of which inherit from Treetop::Runtime::SyntaxNode.

The root of the tree is an instance of Documentation::Doc. It comprises one or more instances of Documentation::Section; which in turn comprise language elements like namespaces, classes, constants, etc., all of which have class representations.

Rendering phase

Next, PDoc asks a generator how to translate this abstract tree into a hierarchical document. The default generator outputs organized HTML in a manner similar to RDoc's.

The HTML generator (PDoc::Generators::Html) has associated templates (in the templates directory) that accept syntax nodes and echo their metadata onto the page using ERB. Templates are modular, so it's quite easy to apply a custom "skin" to one's documentation pages.

Furthermore, generators themselves are modular; PDoc can, theoretically, parse once and render to several different targets (HTML, DocBook XML, CHM, PDF, even ScriptDoc.) We hope many such generators will exist in the future.

Something went wrong with that request. Please try again.