aac5915df7
* Further documentation.
* Decided to add an `include` directive. This will have reprecussions directly
for the JLPPegParser, Directive, and LinkAnchor classes. Include needs more
semantic meaning than we currently have in the process because the author
needs some way to understand what is being included. If you include an org
link defined earlier does it include the whole file? Just that doc block? Both
may be the desired behavior in different situations, but I do not want to add
a complex syntax for selecting, just name the link. Therefore there must be
something about the link that determines how much in included. This means we
need more information in LinkAnchor, some link `type` at a minimum. My current
thought is:
* @org defined links--this is the only type of LinkAnchor defined right
now--always bring the whole DocBlock when they are included.
* A new type of link anchor, call them source file links, bring the whole
file when they are included. These types of anchors would be automatically
created by the parser/generator (have not decided where it belongs yet).
The whole SourceFile would need to be included, but we do not want to emit
the normal header for the file so we may have to do somthing about the
initial emit method.
* Additional types of link anchors arise when we add language awareness to
the process. In my current vision we will automatically add link anchors
of different types when we parse code sections (function definition, class
definition, etc.) and the include directive would bring in all the
DocBlocks related to that code node.
* Additional types of link anchors will arise when we implement the @api
directive, we will think about that in the future.
* Updated the JLPPegParser to recognise include directives.
* Added the include directive to Directive.DirectiveTypes
|
||
|---|---|---|
| doc | ||
| lib | ||
| resources | ||
| src | ||
| .gitignore | ||
| build.xml | ||
| jdb-build-1.9.xml | ||
| project.properties | ||
| README.md | ||
Overview
Jonathan's Literate Programming is my take on literate programming. This project grew out of a desire for a documentation system that:
- generates all documentation from source-code comments,
- is capable of facilitating both JavaDoc-style API documentation as well as literate programming style of documentation,
- has pluggable formatting (default to Markdown),
It is inspired by Donald Knuth's concept of literate programming, as well as the Docco system. I wanted something that provided the readability of Docco but was more full-featured. To that end, JLP currently features:
-
Documentation alongside code, distinct from normal comments.
JLP uses a javadoc-like extra delimiter to seperate normal comments from JLP comments.
-
Support for multiple languages out of the box.
JLP allows you to define custom comment delimiters for any language that supports single-line or multi-line comments. It comes configured with default settings for several languages. Ultimately I hope to cover most of the common programming languages.
This project is in its infancy and some of the larger goals are still unmet:
-
Syntax highligting.
All code blocks will be highlighted according to the language they are written in.
-
Code awareness.
JLP will understand the code it is processing. This will require building a parser for each supported language. By doing so JLP will be able to generate javadoc-style API documentation intelligently, and allow the author to reference code features in a native way (think javadoc @link but more generic).
-
Documentation Directives
Generally I want documentation to conform to code, not code to documentation, but I think some processing directives to JLP (how to combine several files into one, or split one in to many for example) would be useful.
In the same line of thought, it would be usefull to be able to switch the presentation layer of the documentation system depending on the type of file being displayed. For example, interface definitions and core pieces of the API may work better with a side-by-side layout whereas implementation details may work better in an interleaved layout. JLP processing directives would allow the author to specify which is intended on a file (or block?) level.
Project Architecture
Control and Flow
-
The entry point to the JLP executable. Parses the command line input and sets up the processor.
-
The Processor processes one batch of input files to create a set of output files. It holds the intermediate state needed by the generators and coordinates the work of the parsers and generators for each of the input files.
Parsing
-
A very simple interface for parsing JLP input.
Abstract Syntax Tree
-
The top-level AST element. This represents a source file.