I have been playing around with various methods of documentation and for a while I thought the way to go was inline documentation where the documentation exists within the source code, but I’ve noticed a few flaws in this approach.
Who is the target reader?
Inline documentation doesn’t make sense if the end user has no knowledge or interest in the source. It should exist to teach the reader how and why the code works from the perspective of someone interested in the internals. For a developer who just wants to make use of the API, why include it with the source?
Forcing Object-Oriented-ness
JSDoc in particular generates documentation similar to JavaDoc; a strictly Object Oriented language. This doesn’t cross over well when you have things such as chaining, currying or other JavaScript oddities.
The solution
Damon Oehlman wrote about using a Domain Specific Language (DSL) in an external document for API documentation. In his example developers would use some specific representations of how to use the API using text.
I imagine a structure where the documentation mimics the source code file structure, but for every code file a documentation file exists in its place. These files will be a superset of Markdown with extra formatting to denote namespaces, signature overloading, types and internal links. A generator would then convert the structure into HTML pages.
I’ll start with an example:
#Core.Crafty()
>Crafty(selectors:string) => <Core.Entity>
>Crafty(entityID:number) => <Entity>
Select a set of or single entities by components or an entity's ID.
Crafty uses syntax similar to jQuery by having a selector engine to
select entities by their components. Selecting by multiple components
is done by seperating with a comma or a space. A comma is similar
to OR where the entities can match one or more of the components.
A space is similar to AND where entities have to match all the
components.
##Example
Crafty("MyComponent")
Crafty("Hello 2D Component")
Crafty("Hello, 2D, Component")
The first selector will return all entities that has the component
MyComponent. The second will return all entities that has Hello
and 2D and Component whereas the last will return all entities that
has at least one of those components (or).
**See also: <Crafty.map.search>**
In Markdown, a line starting with a single # means Heading 1. This will also denote a unit of code to document; such as a function, namespace or variable. It will also be used as the path for any other references in the documentation.
Grouping can be done by creating a path with a dot . as the separator. This could be used for categorising units of code or specifying a namespace path or even both at the same time!
As per Damon’s example, the greater than symbol > denotes a method signature where you specify the arguments as name:type (name is optional). The return type is specified after =>.
In my example the return type is wrapped in <angled brackets>. This represents an internal link to another unit. You may either specify the full path (as specified after the #) or use a subset of the path (assuming no collision) and the generator will pick it up.
Special files could be used for an Introduction, License information and even tutorials.
#Tutorial.RPG Demo
My tutorial formatted in Markdown!
The output of this format would be a hierarchy of units where each unit has its own HTML page. Templates for headers and footers would allow stronger customisation.
I would be interested in hearing some ideas on the subject. I think external documentation can create a greater separation between how to use the code and how the code works. It avoids huge source code files and can let the developers document in the format that suits the project.
