io-docs

Docstring extractor for Io source code, made as a replacement for the default DocExtractor & co, which are (in author's opinion) very nice examples of hardcore spagetti-code, done the Io-way.

The extractor consist of several objects you need to to know about, to be able to modify the internals the way you need (however, this knowledge is not required to actually use the tool :]):

Meta

Metadata container object, all documentation system statements are parsed and aggregated in this object. The name of the metadata origin is stored in the Meta object slot; the rest of the meta tags are accessible in the same way (see example). By default, all of the availible tags are initialized with an empty string (""), except for Meta category, which defaults for Uncategorized.

Example:

Io> meta := Meta with("UnitTest description Yet, another test framework.")
==> Meta for `UnitTest`
Io> meta object
==> UnitTest
Io> meta description
==> Yet, another test framework.
Io> meta license
==>
Io> meta category
==> Uncategorized

MetaCache

The name of this object is pretty self explanatory. MetaCache is a container for Meta objects, providing to ways of accessing them:

by object name

Io> MetaCache["UnitTest"]
==> Meta for `UnitTest`

Io> MetaCache["SomeObject"]    
==> Meta for `SomeObject`

Note: if the Meta with a given name isn't contained in the MetaCache it will be created and put into the cache.

by category

Io> MetaCache{"Testing"}
==> list(Meta for `UnitTest`)

Io> MetaCache{"SomeCategory"}
==> list(Meta for `SomeObject`, Meta for `SomeOtherObject`, ...)

DocExtractor

Given a path, this object recursively walks all the underlying subdirectories, extracting metadata from Io source files (*.c, *.h, *.io) and putting it into the MetaCache object, described above. The object can do the extraction in two modes: if you want the overall progress to be displayed, during the extraction use DocExtractor run method, else use DocExtractor runQuiet, which will do the job without a single line printed :].

Example:

Io> DocExtractor with("../io/libs/iovm/") run
Extracting docs starting from `../io/libs/iovm`:
................................................................................
.....................
--------------------------------------------------------------------------------
Processed 101 files, 40 objects, 983 slots in 1.161008s

DocFormatter

This object works with data contained inside the MetaCache, renders it and dumps the result to the DocFormatter path directory. By default, two formatters are availible, HTMLDocFormatter and JSONDocFormatter, both support the same running scheme as DocExtractor (i.e. run and runQuiet).

Example:

Io> DocFormatter as("json") with("reference/") run
Generating documentation files in `reference/` using JSONDocFormatter:
.
--------------------------------------------------------------------------------

Note: the path, passed to DocFormatter with method should have a trailing slash, due to a bug in the Directory object.

TODO

The project is still very experimental and even though most of the functionality is covered with unittests, there's lots of bugs around, so don't expect much, really. Here's a list of stuff that needs to be implemented:

• module support for Meta object
• clean-up method for DocFormatter
• filename and line numbers for each method, f.ex.: reduce(accumulator, element, start) [A3_List.io:70]
• an option for generating relative paths instead of absolute ones
• make js-search work with the new internals