Prefer American English. Examples:
All documentation for a topic must be in a single folder under
Non-core module should just use their name for a topic (eg
webshop) or as a prefix (eg
A topic folder must contain a topic.xml, eg:
<topic xmlns="http://www.webhare.net/xmlns/dev/topic" title="Newsletter" shortdescription="Newsletter (Pronuntio)" docorder="harescript changelog"> <section name="api" title="Newsletter API" /> </topic>
A topic may also contain an
intro.md which will be displayed on the topic's landing page.
does not need to listed in the docorder
The docorder describes the order of the
md files, and the
<section>s describe the order of
The prolog is the first comment (before any loadlib) and describes the topic under which this library should be filed:
<?wh /** @topic mytopic/section */ LOADLIB ...;
When a library is public (eg. not in
/tests/ subdirectory), its public symbols
will be documented. This can be overridden at the library level by specifying
@private, optionally followed by a reason.
This topic, and whether the symbol is documented can also be overridden at the symbol level.
Per symbol (function, variable, objecttype or objecttype member):
/** @short Inverse of %OtherFunction @long Long, just like %OtherFunction @loadlib Recommended library to LOADLIB, if not this one @param(object wrdschema2017) wrdschema WRD schema passed as argument 'wrdschema' @param language Language code @param options Options (but shouldn't we just leave this out) @cell(integer) options.int Gimme an int! @return(object wrdschema) Iets over de returnwaarde @cell(integer) return.int Returns an int! @related <!-- Ignore for now? --> @example ``` // Prints 42 PRINT(ToString(21+21)); ``` */ MACRO Print()
@shortis optional, the first line after
///will always be interpreted as the short description
///is technically equivalent to
/**but only really usable for specifying a short description but nothing else
@private(with an optional comment) to mark identifiers that should not be documented
@public(with an optional comment) to mark identifiers that should be documented. When documenting a public symbol that is exported from a public library, you should probably also use
@loadlibto specify which library the user should loadlib for access to this symbol.
@includecelldef [filename]#symbol.parameterto reuse cell definitions from a different function
@signatureto hardcode the signature shown for a function (eg to hide VARIANT parameters)
- for example:
@signature FUNCTION PTR FUNCTION MakeFunctionPtr(STRING functionname)
- for example:
@loadlib(with a library name) to specify which loadlib should be used to get access to this symbol (that library must export this symbol)
Symbols are filed under their library's topic, unless overridden using
/* Refers to /lib/payments.whlib in the same module, objecttype PaymentAPI, member StartPayment's errors cell in the return value @cell(record array) return.errors @includecelldef /lib/payments.whlib#PaymentAPI::StartPayment.return.errors */ /* Use the options supported by another function as the base for your options and extend them: @param options Options @includecelldef %ScanBlob.options @cell(boolean) options.extractdominantcolor If TRUE, extract the dominant color from images */
Code site internal linking
Symbol-search based link
An identifier prefix with
%AllowToSkipCaptchaCheck) will use the symbol
search rules to look for the identifier in the current public libraries. The symbol
needs to be unambigously one of
- a documented global function or variable (including tables and schemas)
- a documented objecttype
- a documented member function of a documented objecttype which is not an UPDATE.
"Documented" means that it's either public in a public library, or has been
explictly marked in the
@documents section of a public library.
% is currently only (officially) supported in HareScript and Markdown documentation.
You can also directly refer to a member of an objecttype using the syntax
%Objecttype::Member. The objecttype must be a documented one, but the member can
now also refer to an UPDATEd member.
Direct links to topics look like this:
[Forms api](topic:forms) or
Relative links are also supported between Markdown documents, eg
when used in the 'getting started' document