Index

Ufydoc

Introduction

This document describes how you can use documentation inside your ufy code that can be extracted by the interpreter itself. It also describes how this documentation can be formatted in such a way to achieve the two most important aspects of documentation: exact metadata and clear layout.

The '#doc' directive

The '#doc' directive, which acts as a substitute of a closing curly brace (and also has a closing curly brace) allows you to store documenation text with a parse node in the parse tree in the following way (Example):

function plusone(a) {
  return (a+1);
#doc
  returns: the argument plus one.
}

It's a simple trick; as soon as the lexer finds a '#doc' directive, it will scan the rest of the text until it finds the closing curly brace, at which point it will go on about its lexing business, storing the documentation in the meanwhile. Is there a problem with that ? Just one, namely if we want the closing curly brace to be in the text. For one, opening and closing curly braces within documentation are counted, so there's never a problem with this, for example:

{
  somecode();
#doc
  why have a { } block here ?
}

Here the opening and closing curly braces in the sentence are matched and ignored. Only the next instance of a closing curly brace is seen as closing the documentation section. But can we denote a single, unmatched closing curly brace in documentation ? No. Not really. But we can hide it from showing up in the generated documentation, using a 'hidden'-tag, which will be shown later on.

Ufydoc

Ufydoc, the tool that extracts parse tree node documentation and changes it to comprehensible output in a format of your choosing, is nothing more than a text-parser. When it encounters a parse tree node with documentation, it combines what it knows at that point, and forges it into an output structure, taking into account: the place it found it the documentation, what else it knows about the place, what else it knows about you, what else is knows about the rest of the documentation in its current run, and what parseable tokens there are in the documentation text.

Command line options

Without any options, ufydoc scans the directories below the current working directory, uses HTML as output format, and puts the generated documentation inside the ufydoc directory tree inside the user's home directory. Below are the command line options to the ufydoc tool to change the default behaviour.

Usage: ufydoc [options]
-d <dir>
-o <dir>
-f <html|xml|pdf|man>

Metadata

The general concept of metadata to be processed by the ufydoc parser, is an identifier, at the beginning of a line, followed without whitespace by a colon (':') character. These separate the different pieces of text, whereby any whitespace is compressed into a single space, except for two each other following returns, which denote a paragraph.

Example:

author: Mr Smith
date: 2006-07-05

• Command line
• Automatic cross referencing within the code itself
• Automatic cross referencing within different ufy files
• Functions, constructors, destructors, methods
• Other blocks

Functions, constructors, destructors, methods

Callables have much more information surrounding them when they are being transformed into documentation; the interpreter knows the name of the function, its parameter signature and, if it's a class, what superclasses it inherits. That is a good thing, because callables form the primary target for documentation; they are the interfaces to any API user.

Callables have special identifiers to indicate callable-specific metadata. They are 'returns' and 'param<n>' and serve to illustrate, respectively, the return value of this particular callable, and whatever pops into your mind about its parameters, where <n> represents a number, from one upwards.

returns:

Layout

• Standard sections
• Headers
• References
• Indents
• Examples
• Code output

Standard sections

author:

date:

synopsis:

description:

seealso:

bugs:

Headers

h1:

h2:

h3:

h4:

hidden:

This is tag that can be used to hide text from the eventual output. Things like to-do lists, remarks to other programmers concerning documentation, or hiding the one, unbalanced opening curly brace from disturbing the ufy lexer can be placed here.