joe doc

The joe doc processor is used to extract JoeDoc documentation comments from .java and .joe source files, and from them generate Markdown API documentation.¹

The API sections of this user's guide were generated by joe doc.

• Documentation Set
  • Documentation Comments
  • Entity Tags
  • Example
• Entity Types
  • The @package Entity
  • The @packageTopic Entity
  • The @function Entity
  • The @type Entity
  • The @enum Entity
  • The @typeTopic Entity
  • The @constant Entity
  • The @static Entity
  • The @init Entity
  • The @method Entity
  • The @mixin Entity
• JoeDoc Links
  • Qualified Type Names
  • Entity Mnemonics
• Running joe doc
  • Configuring joe doc
  • Generated Files

Documentation Set

A documentation set is the generated JoeDoc documentation for the packages in the current project. It will include documentation for the following types of entity:

• Packages
  • Functions
  • Types (including Enums)
    • Constants
    • Static Methods
    • Initializers
    • Methods
  • Additional topics concerning a specific package or type
• Mixins
  • A pseudo-type used for documentation content to be included in multiple types.

Unsurprisingly, this is the same structure you'll find in the Extending Joe section. And unsurprisingly, the generated documentation has this same structure.

Documentation Comments

A documentation comment is a block of comments beginning with the following marker comment: //** and continuing through contiguous comment lines until the next non-comment line:

// Not in a doc comment

//**
// @package my.package
//
// Information about `my.package` in Markdown format.
// ...

// Not in a doc comment

The comment prefix // must be the first non-whitespace text on each line.

joe doc extracts all doc comment lines from a source file, removes the comment prefixes, and then parses them to extract the documentation according to its structure.

Entity Tags

In the example just shown, the tag @package indicates that the following comment text concerns the named package. joe doc understands the following entity tags.

• @package <name>
  • @function <name>
  • @type <name>
    • @constant <name>
    • @static <name>
    • @init
    • @method <name>
    • @typeTopic <name>
  • @packageTopic <name>
• @mixin <name>
  • @constant <name>
  • @static <name>
  • @method <name>
  • @typeTopic <name>

This is the same outline shown above, and purposely so. Each entity has a parent, and the parentage is indicated by the outline.

• @package and @mixin entities belong to the documentation set.
• Every @function and @type entity belongs to the @package that most nearly precedes it in the same file.
• Every @constant, @static, @init, and @method entity belongs to the @type or @mixin that most nearly precedes it in the same file.
• It's an error if the expected parent entity is missing.
• joe doc checks carefully for duplicate names.
• A @type can have at most a single @init (initializer) entity; and it has no name because it always has the same name as its type.

Packages are special; a single Joe package's code is often spread across a number of files. Thus, the same @package name can appear in multiple files, and the related entities will all be ascribed to the same package.

A single source file may (in principle) contain documentation for multiple mixins, packages and types. If joe doc sees a second @package, it immediately switches to that @package, and so for the others.

Example

Here is the beginning of the documentation in Joe's StandardLibrary.java file:

//**
// @package joe
// @title Joe Standard Library
// The `joe` package contains Joe's standard library.

... java code ...

//**
// @function catch
// @args callable
// @result CatchResult
// Executes the callable, which must not require any arguments.
// Returns a [[CatchResult]] indicating success or failure and providing
// the returned result or the error message respectively.
        
... java code ...

This file defines the package itself, and the functions in the package. Consequently, it begins with a comment describing the @package, and the goes on to document each @function in turn. Some things to note:

• Each entity's documentation begins with its @entity tag.

• This is followed by metadata tags: @title for the @package and @args and @result for the @function.

• And these are followed by any number of lines of Markdown text. All such lines will be accumulated and ascribed to this entity until the next entity tag is seen.

Entity Types

This section describes each entity type and its metadata.

The @package Entity

The @package entity begins with @package <name>, and has the following optional metadata:

The title string is used in the generated documentation.

The @package entity may have @function, @type, and @packageTopic children.

For example,

//**
// @package joe
// @title Joe Standard Library
// The `joe` package contains Joe's standard library.

The @packageTopic Entity

A package's normal Markdown content goes near the top of the generated package page, below the index but above the function entries. The @packageTopic entity is way to add titled Markdown content at the bottom of the package file, where it is out of the way.

The @packageTopic entity begins with @packageTopic <name>, and has the following metadata:

The title string is used as a header in the generated content, and in links to that content. In theory the @title tag is optional, but in practice one always wants to use it.

The @function Entity

The @function entity documents a global function, and begins with @function <name>. The name should be the name of a function defined in the current package.

The entity has the following optional metadata:

The @args spec is typically a comma-delimited list of argument names, with ... used to indicate a variable length argument list and square brackets used to indicate optional arguments. Here are some examples:

• x: The single argument x.
• x, y: The two arguments x and y.
• start, [end]: The two arguments start and end; end is optional.
• x, ...: The argument x plus any number of additional arguments.
• name, value, [name, value]...: One or more name,value pairs.

The @args tag can be omitted if the function takes no arguments, and can be repeated if the function has two or more distinct signatures.²

The @result's result is a single token, usually either the name of a Joe type or a variable name like value or this. It can be omitted if the function returns nothing (i.e., always returns null). If the result names a type, it will appear as a link to that type in the generated documentation.

The @type Entity

The @type entity documents a type, and so begins with @type <name>. The name should be the name of a type defined in the current package.

The entity has the following optional metadata:

• <mixin> should be the name of a

The @extends <type> tag is used when this type extends (i.e., subclasses) another script-visible type. The <type> should be the name or qualified name of a referenced @type.

The @includesMixin <mixin> tag indicates that this type's documentation should include the documentation from a @mixin defined in this documentation set. The included documentation will be represented as part of the including type.

The @type entity may have @constant, @static, @init, @method, and @typeTopic children.

For example, in the standard library the AssertError type extends the Error type, both of which are visible at the script-level.

//**
// @type AssertError
// @extends Error
// ...

The @enum Entity

The @enum entity documents a native Java enumerated type whose binding is created using Joe's EnumProxy<E> type proxy class. An @enum entity is just like a @type entity, except that it automatically includes documentation for the enum's static methods, values() and valueOf, and for the enum's instance methods, name(), ordinal(), and toString().

A simple @enum doc comment will usually need to include only a description of the enum and the enum's @constant entities. If the specific enum defines other static or instance methods, they can be included as well.

The @typeTopic Entity

A type's normal Markdown content goes near the top of the generated type page, below the index but above the various constant and method entries. The @typeTopic entity is way to add titled Markdown content at the bottom of the type's file, where it is out of the way.

The @typeTopic entity begins with @typeTopic <name>, and has the following metadata:

The title string is used as a header in the generated content, and in links to that content. In theory the @title tag is optional, but in practice one always wants to use it.

As an example, the String type uses a @typeTopic to document its format string syntax.

The @constant Entity

The @constant entity documents a constant defined by a type, and so begins with @constant <name>. The name should be the name of a constant actually defined by the current type.

At present, the @constant entity has no metadata tags.

The @static Entity

The @static entity documents a static method defined by the current type, and begins with @static <name>. The name should be the name of a static method defined by the current type.

The @static entity has the same metadata as the @function entity.

The @init Entity

The @init entity documents the current type's initializer function. The @init tag doesn't include a name, as the initializer always has the same name as the type.

The @init entity accepts the @args metadata tag, just as any function or method does, but not the @result tag, as its result is always an instance of the current type.

The @method Entity

The @method entity documents a method defined by the current type, and begins with @method <name>. The name should be the name of a method defined by the current type.

The @method entity has the same metadata as the @function entity.

The @mixin Entity

The @mixin entity is like a pseudo-@type; it contains type content that would otherwise be duplicated in multiple @type entries. Mixin entities belong to the documentation set, not to any specific package, and may be included by any @type entity.

Every mixin begins with @mixin <name>; mixin names must be unique within the documentation set.

Mixins have no metadata tags, and may have Markdown content and @constant, @static, @method, and @typeTopic children.

When a type wants to include a mixin, it uses the @includesMixin <name> metadata tag.

• The mixin's Markdown content is inserted into the type's Markdown content at the location of the @includesMixin tag
• The mixin's children are then added to the type.

A mixin is like a template; the string <type> may be included anywhere in the content of the mixin itself and its children, and will be replaced on inclusion by the including type's name.

For example, the mixin might define:

//**
// @mixin MyMixin
// 
// The `<type>` type is able to...
//
// @method myMethod
// @result <type>
// This method...

Then, another type can include it like this:

//**
// @type MyType
// The `MyType` type represents...
//
// @includeMixin MyMixin
//
// The MyMixin Markdown content is included above, replacing the include tag.

JoeDoc Links

The Markdown content for each entity can of course contain normal Markdown links. In addition, though, JoeDoc supports abbreviated links to any entity in the documentation set. For example, if [[String]] is found in Markdown content for the joe package, it will be replaced by a link to the file documenting the String type.

Qualified Type Names

Every @type entity is defined within a package, and so has two names: its bare or unqualified name, e.g., String, and its qualified name, joe.String.

Entity Mnemonics

Every entity can be identified in a JoeDoc link by its mnemonic, which may be qualified or unqualified.

• An entity can be linked to by its unqualified mnemonic from any Markdown content in the same package.
• An entity can be linked to by its qualified mnemonic from any Markdown content in the entire documentation set.

Thus,

• [[joe.String#method.length]] links to the String type's length method, from anywhere in the documentation set.
• [[String#method.length]] links to the String type's length method, from anywhere in the joe package's own documentation.

Running joe doc

To run joe doc, cd to the folder containing the joe doc configuration file, doc_config.joe, and then run joe doc. In Joe's own case, it looks like this:

$ cd joe/mdbook
$ ls doc_config.joe
doc_config.joe
$ joe doc
...
$

joe doc will report any parsing errors, duplicate entities, or unrecognized mnemonics in JoeDoc links.

Configuring joe doc

The joe doc configuration file, doc_config.joe, is itself a Joe script, using the API defined in the joe.doc package.

Joe's own doc_config.file looks like this (at time of writing):

DocConfig
    .inputFolder("../lib/src/main/java/com/wjduquette/joe")
    .inputFolder("../lib/src/main/resources/com/wjduquette/joe")
    .outputFolder("src/library");

All file paths shown are relative to the location of the doc_config.joe file.

Each inputFolder() method names a folder that contains .java and/or .joe files to scan for doc comments. joe doc will scan for such files in the named folder, recursing down into subfolders.

There is also an inputFile() method that names a specific file to scan.

The outputFolder() method names the folder to receive the generated documentation files.

Generated Files

When run, joe doc produces the following files, all within the configured output directory.

• index.md: A detailed index of the entire documentation set, e.g., the Joe Library API Index.
• pkg.<pkg>.md: The package file for the given package., e.g., pkg.joe.md
• type.<pkg>.<type>.md: The type file for the given type, e.g., type.joe.String.md

The link IDs for the functions in a package file, and for the methods and other entities in a type file, are exactly the same as in the entity mnemonics. Thus, to link to the length method of the String type from outside the documentation set, you'd use the partial URL <folder>/type.joe.String.md#method.length.