Oidoc is a program to produce HTML documentation from comments in source code. A simple markdown syntax can be used in the comments. It is used to generate the online documentation at http://chemoelectric.github.io/objecticon/libref/index.html.
Comments must be placed in the right location in order to be matched by oidoc with the particular thing they are documenting.
Empty comment lines at the beginning or end of a comment block are ignored.
The comment should be placed before the item concerned, as follows :-
# Here is a comment about the procedure.
#
procedure test()
end
# And about the record...
#
record R(x, y, z)
# And the class...
class C(Super1)
# A comment about a method.
public static test()
end
...
endFor a global declaration with one variable, put the comment before the “global” keyword. For a declaration with several variables, put the comments before each variable :-
# For a global with one variable, put the comment here.
global
glob1
global
# For a global with two or more variables, put the first comment here.
# It may take up several lines if desired.
glob2,
# And the second here, and so on.
glob3Alternatively, a one-line comment may follow the variable on the same line :-
global
glob2, # First comment
glob3 # Second commentVariable declarations within a class follow the same pattern :-
class SomeClass()
# This is the place to put a variable declaration with just one
# variable in it.
public static const
VARIABLE
# But with several vars...
private readable
# Put the first one here.
another_var,
# And the next one here, and so on.
and_another,
# And another one
yet_another
# Alternatively, place one-line comments on the same line
private readable
more_var1, # Comment 1
more_var2 # Comment 2An asterisk, followed by one or more spaces, indicates each list item. Each asterisk must be indented to the same level :-
Some text before the list...
* The first item.
More about the first item.
* The second item.
* The third item. The following blank line indicates a paragraph
break in the third item's text.
More about the third item, in a new paragraph.
This line ends the list, since its indentation is less than or equal to the asterisks.Each item is indicated by either
followed by a “.”, and one or more spaces. The actual number or letter values are ignored, except to indicate the start of a list rather than the continuation of an existing one. Like bullet lists, the item numbers or letters must have the same indentation. For example :-
Some text before the list...
1. The first item.
More about the first item.
2. The second item.
3. The third item. The following blank line indicates a paragraph
break in the third item's text.
More about the third item, in a new paragraph.
a. A new list.
b. The second item.
A. Another new list.
B. And its second item.
This line ends the third list, since its indentation is less than or equal to the asterisks.These are slightly different, since the list comprises two kinds of entry, namely titles and definitions. A title is indicated by a “:” followed by the title, with no space in-between. A definition is also starts with a “:”, followed by one or more spaces. Like the other list types, the “:” characters must all align. For example :-
Some text before the list...
:The first title.
: Here is its definition.
This continues the first definition.
:The second title.
: Its definition.
This ends the definition list.There is no need to have a title before a definition. For example, a single definition makes a useful way to do block quotations :-
Some text before the block quotation...
: Edward Frederic "E. F." Benson (24 July 1867 – 29 February 1940) was an English novelist, biographer, memoirist, archaeologist
and short story writer.
This ends the quote.Lists may be nested arbitrarily. A nested list simply needs to use a greater indentation for its particular list indication character ("*“,”:", etc). For example :-
1. The first item
1. A sub-list.
2. Its second item
a. Another sub-list.
b. Another item.
2. Back to the first list.
The endA pre-formatted block of text begins with a line with spaces, followed by one or more tildes. It ends with an identical line. For example :-
Here is a pre-formatted block :-
~~
if x > 0 then
x := -x
~~
Normal formatting again.Note that spaces up to the level of the tildes are stripped from the pre-formatted text, so the above example would have a three character indent, regardless of the indentation of the tildes. This ensures pre-format blocks used within a nested list structure look correct.
A blank line indicates a new paragraph. This will not close any list or list item. For example
* First item.
Still the first item, with a new paragraph.
* Second item.A blank line with a single backtick (`) also indicates a new paragraph, but will close lists and items up to and including the indentation of the level of the backtick. This is rarely useful, but could be used to indicate that a paragraph separated two separate bullet lists :-
* First item.
* Second item; the following blank line with a backtick will close
this list and insert a paragraph.
`
* First item of a different list.
* Second itemHowever, the output is likely to appear the same whether or not the backtick is used. Note that the backtick is not needed to separate two adjacent ordered lists, since the item number or letter indicates the start of a new list (“1”, “a” or “A”).
Bold, italic and underline text can be specified as follows :-
Here is some **BOLD** text
Here is some __Underline__ text
Here is some //Italic// text
Here is some ~~Monospace~~ textThese attributes can be spread over several lines, with the proviso that they cannot escape from an inner list structure to an outer one.
Start //italics
* List
* in
* italics
End italics//. Back to normal.
* List
* Start //italics
* Not in italics
Also not in italics.Note that :// and /// don’t start italics, to avoid clashes with URLs.
If text (within a single source line) is enclosed in backticks, then the output is in monospace font, and an attempt is made to resolve the enclosed text to a symbol in the symbol table created by oidoc from the various source files being documented. If a symbol is found, then an anchor link is produced in the output. For example :-
import io
# This procedure does something with the `Stream` `s`.
procedure p(s)
endHere, `Stream` will resolve to io.Stream, and a link will be created to the documentation for that class. `s`, on the other hand, will not resolve to a symbol, and will just appear in a monospace font.
Note that, within a procedure or method’s comment, parameter names never resolve to symbols. So in the above example, `s` would not produce a link even if there were a global variable of that name. The same applies to record comments and record field names. Should such a link be needed, the fully qualified name must be used.
If, instead of two backticks, a backtick and a quote are used, then the enclosed text is never resolved as a symbol. This gives a shorter way of specifying monospace font with two tildes :-
This is never resolved to `Stream', and looks just like ~~Stream~~.The backtick syntax also provides a way to output characters which would otherwise be interpreted by oidoc as being markdown syntax. For example :-
This shows "x to the power y", as you might expect :- `x ** y`.
But this doesn't : ~~x ** y~~ - it is a mis-balanced combination of monospace and bold font.The only way to output backticks, however, is using a pre-formatted block.
Links to http, file and ftp URLs can be enclosed in angle brackets, as follows :-
Heap's algorithm for permutation generation.
See : <https://en.wikipedia.org/wiki/Heap%27s_algorithm>The output will contain an anchor link to the specified URL.
Two or more spaces at the end of a line indicates a line break.
Contents