qDoc - Kdb+ HTML Documentation Generator

qDoc is a tool for generating API documentation in HTML format from doc comments in q source code.
The qDoc format is heavily based on the JavaDoc format. qDoc is ran from the tools menu, when called it will generate documentation for all open files.

QDoc Command Line

QDoc can be ran from the command line, this allows it to be used as part of automated build systems.

java -cp qstudio.jar com.timestored.qdoc.QDocMain <targetFolder> <sourceFolder> [<baseWeblink>]

Advanced qDoc tags

qDoc understands the most useful JavaDoc-style tags and turns them into structured HTML tables. The parser also reads q function argument lists, so documented functions are shown with their signature, for example .regexp.extract[subject;pattern].

Tag	Purpose	Example
@param	Documents a named function argument.	/ @param tableName symbol naming the table to query
@return	Documents the value returned by the function.	/ @return table of matching rows
@throws or @exception	Documents errors the function may signal.	/ @throws type if the input is not a table
@col	Documents columns returned in a table.	/ @col sym symbol name
@eg or @example	Documents runnable examples. Use one line for short examples, or put @eg on its own line and continue the example on following comment lines. When qDoc is generated with a base web link, each example becomes a clickable link.	/ @eg .regexp.extract["abc123";"[0-9]+"]
@summary	Sets the short description shown in the summary table. Without it, qDoc uses the first sentence and will not split inside dotted q names such as .csv.read.	/ @summary Read delimited text as a table.
@ignore	Hides an item from the generated HTML. In a file header it hides that file and its namespace listing; on a function or value it hides only that item.	/ @ignore

The optional command-line baseWeblink argument is prepended to each URL-encoded @eg or @example value. For example, generating docs with:

java -cp qstudio.jar com.timestored.qdoc.QDocMain docs src "http://localhost:5000?"

turns an example such as / @eg .regexp.extract["abc123";"[0-9]+"] into a link that opens http://localhost:5000?.regexp.extract%5B%22abc123%22%3B%22%5B0-9%5D%2B%22%5D. This is useful for publishing API documentation where examples can be sent straight to a running q server.

Multi-line examples are kept as code blocks until the next tag or paragraph break:

/ @eg / .logger.addHandler[.logger.getConsoleHandler[ / .logger.getLevelFilter[`INFO]; / .logger.getSimpleFormatter[]]] / .logger.info["myClass";"err txt message"]

Use @ignore for compatibility aliases, private bridge names, and other symbols that should not appear as public API. For example, adding / @ignore immediately above .s.e:{...} hides .s.e; if that was the only public-looking member in .s, the .s namespace will not be listed in the HTML navigation.

How to write doc comments for qDoc

Example

/ ######################### logging to disk/table/console / a logger based on java's, including handlers,filters,formatters. But note there is only one global logger. / handlers - are notified when a logging event occurs / formatters - convert a logrecord into a string / filters - restrict what messages are actually logged / . / @eg / .logger.addHandler[.logger.getConsoleHandler[.logger.getLevelFilter[`INFO];.logger.getSimpleFormatter[]]] / .logger.info["myClass";"err txt message"] \d .logger / ### log an actual message, notice its spelt with a Q, loQ, apply all handlers to this latest log entry / @param level - a logger.levels symbol, in order (higher priority first) `SEVERE`WARNING`INFO`CONFIG`FINE`FINER`FINEST / @param class - a string describing the class/namespace the logging is occuring in / @param message - the message to log / @eg .logger.loq[`warn;`logger;"could not connect"] / @eg .logger.loq[`info;`logger;"Connected"] loq:{ [level;class;message] // using a dictionary allows handlers arguments to be changed in future + allows overloading logRecord:(`level`class`message)!(level;class;message); // pass the logRecord to all handlers (til count handlers) handlers \:logRecord; } /### change any arg passed in, into a string frmt:{$[10=abs type x; x; @[{""{x,"\n",y}/.h.td x}; x; "\r\n",.Q.s x]]} / @ignore / Internal values should not be shown in docs. i.internalVal:1; \d .

Generated output

This frame shows the HTML generated from the logger example used by the qDoc Java tests.