Documentation generator for q (`.qd`)

Overview

qdoc is an API documentation generator tool for q/kdb+. The qdoc tool scans your source code for comment blocks right before the code blocks (functions, data, etc.) and generates Markdown documentation for you.

The documentation can be generated from either the q files on disk or an in-memory table of items.

Basic usage

To simply document all the source code for a project, invoke the documentation generator with the path to the project directory. It will recursively go and find *.q and README.md files and document them.

.qd.doc[::] `:/path/to/project

You can also selectively document q file(s) and/or README(s)

.qd.doc[::] `:/path/to/qfile1`:/path/to/qfile2`:/path/to/README

Render Markdown (using mkdocs)

.qd.out.mkdocs.write[::] .qd.doc[::] `:/path/to/project

For more information, see .qd.doc, .qd.out.mkdocs.write

Writing documentation

qdoc's purpose is to document the API of your q project/library. Add the documentation comments directly to your source code, generally placed immediately before the code being documented. Each qdoc comment must start with / or // followed by one of the qdoc tags. Each tag must be prepended with an @ symbol.

Function/data

Use the qdoc tags to document the behavior of a function or a data (variable) item.

Here is a code snippet from an example q file that documents:

A function item .foo.add that takes two arguments x and y of type long and returns the sum as an integer
A data item .foo.PI that holds the value of pi

system "d .foo";

// @kind function
// @fileoverview Function returns the sum of two numbers as an integer
// @param x {long} First parameter 
// @param y {long} Second parameter
// @return {int} Sum of the parameters
add: {[x; y] 
    "i"$x + y
    };

// @kind data
// @fileoverview Static value of pi
PI: 3.14159;

system "d .";

README

qdoc supports documenting the behavior of a namespace or the whole project. Use Markdown files called */README.md to add namespace or project level description.

Namespace description

To add a description for a namespace you will need to use the following qdoc tags:

kind: Use the readme identifier to mark the beginning of the readme comment block for a namespace
name: Name of the namespace being documented followed by /README.md. E.g.: .foo/README.md
category: (Optional) By default category is extracted from the namespace. Use this to specify a non default category name.
subcategory: (Optional) By default subcategory is extracted from the namespace. Use this to specify a non default subcategory name.
end: Marks the end of a qdoc comment block.

The documentation for the namespace, along with the tags specified above, can live in a couple of places:

Embedded: You can embed readme(s) within a q file by classifying the comment block as readme using the kind tag. Multiple readmes for different namespaces can be included within a single q file by starting and ending each readme comment block with kind and end tags respectively. Since the embedded readmes are part of your q file you will need to comment out each line. These comments will be stripped out for you by the qdoc generator.

Here is an example q file that has a couple of embedded readmes for different namespaces followed by arbitrary code:

system "d .foo"

// @kind readme
// @name .foo/README.md
// @category Foo
// # Foo
// This a readme for the .foo namespace. 
// It contains the following items:
//      - .foo.ADD
//      - .foo.PI
// 
// end

// @kind readme
// @name .foo.bar/README.md
// @category Foo
// @subcategory Bar
// # Foo
// This a readme for the .foo.bar namespace.
// 
// end

// Followed by code ...
1+1;

system "d ."

Note: This document is generated by qdoc generator itself, so we can not use the '@end' tag in our examples since that will prematurely end the readme.

All the lines with '// end' should be '// @end' instead

Standalone: You can also have a Markdown file per namespace containing the documentation. Just ensure that the name of the Markdown file ends with REAMDE.md so that the qdoc generator can locate the files. Even with the standalone READMEs, you do need to add the qdoc tags specified above. However, since these are raw Markdown files and would not contain any q code, you do not need to comment out every single line of documentation.

Here is an example of foo/README.md file containing documentation for the .foo namespace

// @kind readme
// @name .foo/README.md
// @category foo
// # Foo
This a readme for the .foo namespace. 
It contains the following items
     - .foo.ADD
     - .foo.PI

Project description

To add a project level description include a README.md file with the project description at the root of the project. The project level readmes do not need any qdoc comments. Contents of this readme file will appear on the index page of the project documentation rendered using the mkdocs plugin.

Project organization

project/
    ├── foo.q
    ├── foo
    │   └── README.md
    ├── bar.q
    ├── README.md
    └── sub-project
        ├── sub.bar.q
        └── sub.foo.q

QDoc output

The qdoc generator converts the qdoc comments blocks in the source code to Markdown documentation. The core .qd.doc function takes two arguments, settings and src, and returns the generated Markdown content. It also writes the Markdown files to disk if the write flag is set in the settings dictionary.

On disk

By default, the generated Markdown files are written to disk at ${pwd}/out. This can be overwritten by using the out attribute in settings dictionary.

The out directory contains md subdirectory that holds a Markdown file per category/subcategory depending on the value of the group attribute in the settings. The files are named after the category/subcategory and each file contains the associated items (functions, data, readmes). By default, the category and subcategory information is extracted from the item name. The top-level namespace becomes the category and sub-namespace (if any) becomes the subcategory. Here are a few examples:

item name	category	subcategory
.foo.bar	foo	-
.foo.bar.baz	foo	bar
.foo.bar.baz.bat	foo	bar.baz
foo.bar	Global	-
foo.bar.baz	Global	-

This behavior can be modified and users can categorize their items on a per-namespace and/or per-item basis. Here is the order of precedence for determining the category and subcategory for an item:

extracted from the item name
defined on the namespace level using the default-category and default-subcategory tags in the onLoad function
defined on per item basis using the category and subcategory tags

See qdoc tags for more information on the usage of these tags.

In memory

The contents of the generated Markdown files are also returned by .qd.doc function along with the errors encountered during the generation.

See .qd.doc for detailed information on the returned data structure.

QDoc tags

qdoc uses case insensitive tags to document the behavior of an item. Unsupported tags are ignored by the qdoc generator. The qdoc tags grammar is divided into two major categories:

General Tags: These tags are used to document the behavior of a particular piece of code. All these tags are supposed to go immediately before the code being documented. Here is the list of all the general tags:

tags	description	multiline
@author	Defines the author of the item	Yes
@category	Categorize an item in the generated Markdown files	No
@deprecated	Marks the item as deprecated	Yes
@desc	Describes the individual properties table/dictionary	Yes
@doctest	Describes executable example blocks	Yes
@end	Marks the end of a readme comment block	N/A
@example	Documents usage example(s) for the item	Yes
@fileoverview	Describes the behavior of the item	Yes
@kind	Defines the kind (type) of the item	No
@name	Defines the name of the item	No
@param	Describes the parameter of the function	Yes
@private	Marks the item as private	N/A
@returns	Describes the return value of the function	Yes
@see	Creates a link to another item in the documentation	No
@subcategory	Categorizes the item in the generated Markdown files	No
@throws	Documents an error that the function might throw	Yes
@todo	Documents the tasks that still need to be done	Yes

Special Tags: qdoc supports special tags that define/modifies the properties of code blocks on a namespace basis. These tags go inside the function body of a special function named onLoad (case sensitive). You can define an onLoad function for each namespace. E.g. .foo.onLoad, .foo.bar.onLoad. Here is the list of all the special tags:

tags	description	multiline
@default-category	Defines the default category for all items in a namespace	No
@default-subcategory	Defines the default subcategory for all items in a namespace	No
@typedef	Describes the definition of a type in the onLoad function	Yes

Tag mapping

qdoc supports mapping the behavior of a default qdoc tag to a user-defined tag name. This allows users to make use of qdoc generator on an existing project (with user-defined tag names) without having to update the tags.

Example: Map the user-defined overview and arg tag names onto qdoc's fileoverview and param tags respectively

.qd.doc[enlist[`tagmap]!enlist `overview`arg!`fileoverview`param] `:/path/to/project

See .qd.doc for more details.

Note: The behavior of mapping tags of incompatible syntaxes is undefined

Author

Syntax

@author AUTHOR_NAME

Overview

The author tag lets you specify an author name for the item

Examples

Documents Alex as the author of the function

// @author Alex
{[]
    }

Default-category

Syntax

@default-category NAMESPACE CATEGORY_NAME

Overview

The default-category tag lets you specify a category for all the items in a namespace. Since it is one of the special qdoc tags, it should only be used within a function named onLoad.

See the special tags section under qdoc tags for more information on the onLoad function.

Examples

Set the category of all the items under the .foo namespace to Foo

.foo.onLoad: {[]
    // @default-category .foo Foo
    }

Default-subcategory

Syntax

@default-subcategory NAMESPACE SUBCATEGORY_NAME

Overview

The default-subcategory tag lets you specify a subcategory for all the items in a namespace. Since it is one of the special qdoc tags, it should only be used within a function named onLoad.

See the special tags section under qdoc tags for more information on the onLoad function.

Examples

Set the subcategory of all the items under the .foo.bar namespace to Bar

.foo.bar.onLoad: {[]
    // @default-subcategory .foo.bar Bar
    }

Deprecated

Syntax

@deprecated [ALTERNATIVE]

Overview

The deprecated tag marks an item as deprecated. You can use the deprecated tag by itself or include some text that describes more about the deprecation and provides an alternative.

Examples

Documents the function as deprecated

// @deprecated Use bar
{[]
    }

Desc

Syntax

@desc PARAM_NAME.PROPERTY_NAME PROPERTY_DESCRIPTION

Overview

The desc tag is used in conjunction with the param, return and typedef tags to add descriptions for table column or dictionary keys.

A dictionary key/table column can be marked optional by wrapping the name in square brackets.

Examples

Documents the description for the keys of a dictionary parameter. Note that key z is marked as optional here

// @param   foo     {dict (x: int; y: char; z: long)}   Parameter description
// @desc    foo.x   Description of key x
// @desc    foo.y   Description of key y
// @desc    [foo.z] Description of key z
{[foo]
    }

Documents the description for the columns of a table

// @returns foo     {table (x: int; y: char)}   Return description
// @desc    foo.x   Description of column x
// @desc    foo.y   Description of column y
{[]
    }

Documents the description for a data structure defined using the typedef tag

.foo.onLoad: {[]
    // @typedef myType {dict (x: table (y: char); y: dict (x: char))}
    // @desc myType.x   Description for key x
    // @desc myType.x.y Description for table column y in key x
    // @desc myType.y   Description for key y
    // @desc myType.y.x Description for table column x in key y
    }

Doctest

Syntax

@doctest [TITLE]
code
code

Overview

The doctest tag is used to define an executable example that can be conditionally run during qdoc generation time for testing for API doc accuracy. The last line of the code block should return a boolean

Examples

// @doctest Testing the functionality of add function
// x:1; 
// y:2;
// 3 ~ +[x;y]

End

Syntax

@end

Overview

The end tag marks the end of the readme comment block. This tag also allows you to embed multiple readmes in a single q file without any ambiguity.

Examples

Marks the end of a readme comment block. Comments after the end tag are not part of the readme.

// @kind readme
// .
// .
// end

// Stray comments are not 
// a part of the readme

// @kind readme
// .
// .
// end

Note: This document is generated by qdoc generator itself, so we can not use the '@end' tag in our examples since that will prematurely end the readme.

All the lines with '// end' should be '// @end' instead

Example

Syntax

@example [TITLE]
code
code

Overview

The example tag assumes a multi-line comment (until the next tag or the beginning of the function) that shows how the item is intended to be used.

Examples should be titled to convey the purpose of the example. For a longer description, use the paragraph Markdown token > inside of the example block. The output of an example should be shown below the q expression line and should be prefixed with /=>

Examples

Document an example titled 'bar' for a function.

// @example Bar
// // This is a long description of how the example should work.
// // Long descriptions can be multiple lines
//
// foo `AAPL`GOOG`MSFT`AMZN
// /=> "AAPL"
// /=> "GOOG"
// /=> "MSFT"
// /=> "AMZN"
{[]
    : .axq.asString x
    }

Fileoverview

Syntax

@fileOverview ITEM_DESCRIPTION

Overview

The fileOverview tag takes the multiline comments (until the next tag or the beginning of the function) as the overview for the item. A file overview block should describe the external behavior of an individual item. The file overview should not describe the inner workings of an item.

Examples

Document an overview for a foo function.

// @fileOverview This is the description 
// for the function called 'foo'
{[]
    }

Kind

Syntax

@kind ITEM_TYPE

Overview

The kind tag specifies the type of the item. Valid item types are: function, data and readme. The kind tag also marks the beginning of the readme comment block, therefore it should be the first tag when used in a readme comment block.

Examples

Marks the item as a function

// @kind function
{[]
    }

Name

Syntax

@name ITEM_NAME

Overview

The name tag is used to specify the name of the item being documented. There is no need to use the name tag when documenting function/data since these items already have a name associated with them in code. README(s) however do not have a name associated with them, therefore, it is required to use this tag to specify the name for the readme.

The name is also used to categorize an item in the Markdown files. See category and subcategory for more information on how category and subcategory is extracted from an item name.

Examples

The value .foo/README.md for the name tag here specifies that this readme is associated with the .foo namespace

// @kind readme
// @name .foo/README.md

Param

Syntax

 @param PARAM_NAME {PARAM_TYPE} [PARAM_DESCRIPTION]

Overview

The param tag lets you document the parameter for a function you are documenting. It requires you to specify the name of the parameter at the least. You can include the parameter's type enclosed in curly brackets followed a description. Both type and description fields are optional, but it is highly recommended to document them. For information on documenting parameter types, see qdoc types

Examples

Documents name, type, and description of function parameters

// @param bar   {string}    This is the description of parameter bar
// @param baz   {int}       Description of parameter baz
{[bar; baz]
    }

Documents compound parameter types for a function

// @param bar   {(symbol;long; byte)}       This is the description of parameter bar
// @param baz   {table (a:long; b:char)}    Description of parameter baz
{[bar; baz]
    }

Private

Syntax

@private

Overview

The private tag marks an item as private, or not meant for general/public use. Private items are not documented by default, but the behavior can be changed by setting the docprivate flag in the settings.

As a general convention, a module should never call out to another module's private items.

Examples

Documents a function as a private function

// @private
{[]
    }

Returns

Syntax

@returns [RETURN_NAME]  {RETURN_TYPE}  [RETURN_DESCRIPTION]

Overview

The returns lets you document the return value for a function. Optionally, you can specify a name and a description for the return value.

Examples

Documents the return value of a function

// @returns {table (a: int; b: symbol)} Returns a table 
{[]
    : ([] a: til 10; b: 10?`3)
    }

See

Syntax

@see ITEM_PATH [ITEM_PATH ...]

Overview

The see tag allows you to refer to another item that may be related to the one being documented. You can use the see tag more than once in a single item. Multiple items can also be referenced using a single see tag followed by a list of name-paths separated by spaces.

You need to provide a name-path of the other item. You can either use an absolute path (fully qualified name) or relative path (name) of the item being referred to. The relative path should be relative to the current module not the top level module.

Examples

Adds link to functions .bat.quaz and .foo.baz in function .foo.bar. It uses a fully qualified name to reference function .bat.quaz since it belongs to a different module than .foo.bar. The function .foo.baz however, can be referenced with a relative name baz since it is in the same module.

Function name: .foo.bar

// @see .bat.quaz
// @see baz
{[]
    }

// @see .bat.quaz baz
{[]
    }

Subcategory

Syntax

@subcategory SUBCATEGORY_NAME

Overview

The subcategory tag lets you specify a subcategory for the item. This subcategory along with the category is used to organize items in the generated Markdown files. Items with the same subcategory are grouped in the same Markdown file. By default, the subcategory is extracted from the item name.

See qdoc output for information on default subcategory

Examples

Sets the subcategory to bar

// @subcategory bar
{[]
    }

Throws

Syntax

@throws {THROW_TYPE} [THROW_DESCRIPTION]

Overview

The throws tag allows you to document an error that the function might throw.

Examples

Documents that the function throws an "Invalid Argument Type" error

// @throws "Invalid Argument Type"
{[]
    if[1b;
    '"Invalid Argument Type"];
    }

Todo

Syntax

@todo TODO_DESCRIPTION

Overview

The todo tag allows you to document tasks that need to be completed. You can use the todo tag more than once in a single item.

Examples

Documents the tasks that need to be done

// @todo This task needs to be done
// @todo This task also needs to be completed
{[]
    }

Typedef

Syntax

Definition:

// @typedef ALIAS_NAME {ALIAS_TYPE} [TYPEDEF_DESCRIPTION]

Usage:

// @param PARAM_NAME {#ALIAS_NAME} [PARAM_DESCRIPTION]

Overview

The typedef tag allows you to describe an alias for your data structure and then use the alias as type everywhere instead of the data structure. You can optionally use the desc tag to define the keys/columns of the datastructure.

A private data structure can be created using typedef:private tag. Private data structures are not documented by default, but the behavior can be changed by setting the docprivate flag in the settings.

Since it is one of the special qdoc tags, it is supposed to be used in the onLoad function body only. See the special tags section under qdoc tags for more information on the onLoad function.

qdoc typedefs are categorized into two types:

Basic typedefs: Typedefs that accepts no arguments
Advanced typedefs: Typedefs that accepts argument(s). Wrap the arguments to the advanced typedef using angle brackets (< and >) if they are nested.

Examples

Describes basic typedefs in the onLoad function

Typedef definition:

.foo.onLoad: {[]
    // @typedef         firstType   {int}                    This is my first type.

    // @typedef:private secondType  {dict (a: int; b: char)} This is my second type.
    // @desc secondType.a Description for key a
    // @desc secondType.b Description for key b
    }

Typedef usage: (any function in the .foo namespace)

// @param   newParam1   {#firstType}    This is new param 1. 
// @param   newParam2   {#secondType}   This is new param 2.
.foo.bar: {[newParam1; newParam2]
    }

QDoc Output:

|   Name    |   Type    |                   Description                 |
| --------- | --------- | --------------------------------------------- |
|newParam1  |int        |This is new param 1. This is my first type.    |
|newParam2  |dict       |This is new param 2. This is my second type.   |
|newParam2.a|int        |Description for key a                          |
|newParam2.b|char       |Description for key b                          |

Describes advanced typedefs (with parameters) in the onLoad function

Typedef definition:

.foo.onLoad: {[]
    // @typedef thirdType a     {table (a: #a; b: char)}
    // @typedef fourthType a b  {(#a; #b)}               
    }

Typedef usage: (any function under the .foo module)

// @param   newParam3   {#thirdType long}           This is my new param 3
// @param   newParam4   {#fourthType int char[]}    This is my new param 4
// @param   newParam5   {#fourthType <#thirdType double> <#thirdType int>}
.foo.bar: {[newParam3; newParam4; newParam5]
    }

QDoc Output:

|   Name    |       Type        |                   Description         |
| --------- | ----------------- | ------------------------------------- |
|newParam3  |table              | This is my new param 3                |
|newParam3.a|long               |                                       |
|newParam3.b|char               |                                       |
|newParam4  |\(int; char\[\]\)  | This is my new param 4                |
|newParam5  |\(table \(a: double; b: char\); table \(a: int; b: char\) ||

Describes typedefs with scope referencing

Typedef definition:

.foo.bar.onLoad: {[]
    // @typedef myType      {table (moduleName: symbol; typedef: string)}
    // @typedef secondType  {symbol}    This is a new second type.
    }

Typedef usage: (any function under the .foo namespace)

// @param   newParam5   {#.foo.bar.myType}  Fully qualified name naming.
// @param   newParam6   {#bar.secondType}   Relative naming. 
.foo.bar: {[newParam5; newParam6]
    }

QDoc Output:

| Name                  | Type  | Description                               |
| ----------------------| ----- | ----------------------------------------- |
|newParam5              |table  | Fully qualified name naming.              |
|newParam5.moduleName   |symbol |                                           |
|newParam5.typedef      |string |                                           |
|newParam6              |symbol | Relative naming. This is a new second type|

QDoc types

The following table outlines a brief overview of the supported qdoc types:

type	input example	documentation	documentation example
atom	`1`	Atom type name	long
anything	`(1i; 100; "a")`	Global typedef `any`	#any
dict	`a`b!(1; "x")	Key value type specifier	dict (a:long; b:char)
enum	(`a`b)?(`a`b`b`a)	Enumeration symbol	$symbol
function	`{"i"$x}`	Function param & return	fn (long) -> int
hsym	`:path/to/file`	Global typedef `hsym`	#hsym
option/or	One type or the other	Type 1 `\|` Type 2 `\|` Type N	table `\|` dict [] `\|` dict
string	`"Hello, World"`	Term `string`	string
table	`([] a:1 2;b:"xy")`	Key value type specifier	table (a:long; b:char)
tuple	(`a; 0; 0x61)	Tuple type specifier	(symbol; long; byte)
typedef	Could be anything	Typedef reference	#myTypedef
vector	`1 2 3 4 5 ...`	Vector type and []	long[]

To validate a qdoc type, you can pass the qdoc type to the function .qd.types.parse as string. The type has valid syntax as long as the function returns a parse tree and does not throw any error.

.qd.types.parse "(symbol; long)"
//=> `option ,(`tuple;((`option;,(`atom;((`atom;"symbol");(`array;0))));(`option;,(`atom;((`atom;"long");(`array;0))));(`array;0)))

.qd.types.parse "innt"
//=> `Error parsing at line 1, column 0: expected "dict", "fn", "any", "bool", "guid", "byte", "long", "real", "char", "date", "time", "null", "type", "int", "*", "#", "{", "$", "("

The variable .qd.TYPES holds a list of all the supported qdoc types. These types can be widely catgeorized in three categories:

Primitives

qdoc atomic types include q's primitive atoms and vectors ranging from type ± 1h to 19h.

To build a vector append square brackets at the end of all types expect function and typedef type:

Array of function: fn [] (long) -> int
Array of typedef with argument: #myTypedef [] <arg1> <arg2>

// List of supported atoms
`bool`boolean`byte`char`character`date`datetime`float`guid`int`integer`long`minute`month`real`second`short`string`symbol`time`timespan`timestamp

// List of supported vectors
`bool[]`boolean[]`byte[]`char[]`character[]`date[]`datetime[]`float[]`guid[]`int[]`integer[]`long[]`minute[]`month[]`real[]`second[]`short[]`string[]`symbol[]`time[]`timespan[]`timestamp[]

Compound

qdoc compound types include tuple, table, dictionary, and function, which corresponds to q's type 0, 98, 99 and 100h respectively.

Tuple

A tuple/general list is represented by a list of qdoc types wrapped in parens and separated by semicolons.

(QDOC_TYPE; QDOC_TYPE ...)

Examples:

// An empty tuple/general list
    ()

// A tuple of any type
    (#any)

// A tuple of int and char array
    (int; char[])

// A tuple of a dictionary, float, symbol and a lambda
    (dict (x: long; y: symbol); float; symbol; fn)

// An array of tuple
    (guid; symbol)[]

Table

A table is represented by the table keyword followed by key-value pairs separated by colons.

Simple Table:

table (COLUMN_NAME: COLUMN_TYPE; COLUMN_NAME: COLUMN_TYPE ...)

Keyed Table:

table ([COLUMN_NAME: COLUMN_TYPE] COLUMN_NAME: COLUMN_TYPE ...)

Examples:

// A table with no column definition
    table

// A table with column foo of type int
    table (foo: int)

// A table with two columns (square brackets are not necessary here)
    table ([] foo: long; bar: fn)

// A table and a dictionary within a table
    table ( foo: table (x: int); bar: dict (y: char))

// A keyed table with foo as the key column of type symbol
    table ([foo: symbol] bar: int )

// An array of table
    table (foo: long; bar: fn)[]

Dictionary

A dictionary is represented by the dictionary or dict keyword followed by key-value pairs separated by colons.

dictionary (KEY_NAME: VALUE_TYPE; KEY_NAME: VALUE_TYPE ...)

Examples:

// A dictionary with no definition
    dictionary

// A dictionary with key foo of type int
    dict (foo: int)

// A dict with two keys
    dict (foo: long; bar: fn)

// A table and a dictionary within a dictionary
    dict ( foo: table (x: int); bar: dict (y: char))

// An array of dictionary
    dict (foo: long; bar: fn)[]

Function

A function is represented by the function or fn keyword followed by function parameter and return types. Only monadic functions can documented currently.

function (PARAM_1_TYPE; PARAM_2_TYPE; ...; PARAM_N_TYPE) -> RETURN_TYPE

Examples:

// A function with no definition
    function

// A function that takes an integer and returns a long
    fn (int) -> long

// A function that takes a dictionary and returns a table
    fn (dict(x: symbol)) -> table(x: symbol)

// A function that takes three arguments and returns a guid
    fn (long; symbol; char) -> guid

// An array of functions
    fn[] (int) -> long[]

Special

qdoc supports a few special types:

type	description
`*`	Represents any type
`null`	Represents any null type
`number`	Represents any numeric type
`string`	Represent a char vector
`#hsym`	Global typedef for file paths
`#any`	Global typedef for any type

.qd.TAGS

Returns a symbolic list of valid QDoc tags.

.qd.TYPES

Returns a symbolic list of valid QDoc types.

.qd.doc

Generates markdown documentation from given q files on disk or a table of items. Default output location for the generated markdown files is ./out/md directory.

Parameters:

Name	Type	Description
settings	.qd.settings	Optional Argument. Pass empty dictionary to use default settings
src	.qd.src	Source of the data to be documented. You can document using q files on disk or a table of items

Returns:

Type	Description
.qd.output	A dictionary of path to the output directory (MD files), markdown content in each file and the table of errors

Example: Generate qdoc from all the files (\*.q, \*.README and \*.README.md) in the current directory with different settings.

 // Default settings
      .qd.doc[::] `.

 // Write the generated markdown files to the specified directory
      .qd.doc[(enlist `out)!enlist `:mydir] `.

 // Map user defined `description` and `arg` tags to qdoc's `fileoverview` and `param` tags respectively
      .qd.doc[(enlist `tagmap)!enlist `description`arg!`fileoverview`param]  `.

 // Exclude items whose name matches the *.i.* expression
 // Option 1: By default it will use like 
      .qd.doc[(enlist `exclude)!enlist "*.i.*"] `.
 // Option 2: Use like expression 
      .qd.doc[(enlist `exclude)!enlist (`like;"*.i.*")] `.
 // Option 3: Use regex expression 
      .qd.doc[(enlist `exclude)!enlist (`regex;".*\\.i\\..*")] `.

 // Document items marked as private or have todo tags or have no qdoc tags
      .qd.doc[`docprivate`doctodo`docempty!111b] `.

 // Do not search for files recursively
      .qd.doc[(enlist `recursive)!enlist 0b] `.

 // Do not write generated markdown files to disk
      .qd.doc[(enlist `write)!enlist 0b] `.

Example: Generate qdoc from files (\*.q, \*.README and \*.README.md) on disk with default settings

 // Document all the files in the current directory
      .qd.doc[::] `.

 // Document all the files from the specified directory
      .qd.doc[::] `$"/dir/to/files"

 // Document only the specified files
      .qd.doc[::] `:dir/foo.q`:foo.q`:dir/foo.README.md

Example: Generate qdoc from a table of items

 items: ([] 
      name: `.foo.bar`.foo.baz`.foo.bat.bar`.foo.bat.BAZ,`$(".foo/README.md"; ".foo.bat/README.md");
      kind: `function`function`function`data`file`file;
      content: (
          "// @fileoverview Description for .foo.bar\n// @category FOO\n// @subcategory\n// @param x {int}\n// @return {long[]}\n{[x]\n til x\n}";
          "// @fileoverview Description for .foo.baz\n// @category FOO\n// @subcategory\n// @param x {int}\n// @return {int[]}\n{[x]\n \"i\"$til x\n}";
          "// @fileoverview Description for .foo.bat.bar\n// @category FOO\n// @subcategory BAT\n// @param x {int}\n// @return {byte[]}\n{[x]\n \"x\"$til x\n}";
          "// @fileoverview Description for .foo.bat.BAZ\n// @category FOO\n// @subcategory BAT\nrand 100";
          "// @kind readme\n// @category FOO\n// @subcategory \n# Foo Module\nThis is a readme for .foo module\n ...";
          "// @kind readme\n// @category FOO\n// @subcategory BAT\n# Foo.bat Module\nThis is a readme for .foo.bat module\n ..."
          )
      );
 .qd.doc[::] items

.qd.docws

Deprecated

This function has been deprecated. You can now right click a repository/module/file in the workspace to generate doc. You can also use .qd.doc to generate doc manually.

Parameter:

Name	Type	Description
x	.any	Any kdb+ type

Throws:

Type	Description
	"Deprecated: Use .qd.doc instead"

See Also: .qd.doc

Documentation generator for q (.qd)

Overview

Basic usage

Writing documentation

Function/data

README

Namespace description

Project description

Project organization

QDoc output

On disk

In memory

QDoc tags

Tag mapping

Author

Category

Default-category

Default-subcategory

Deprecated

Desc

Doctest

End

Example

Fileoverview

Kind

Name

Param

Private

Returns

See

Subcategory

Throws

Todo

Typedef

QDoc types

Primitives

Compound

Tuple

Table

Dictionary

Function

Special

.qd.TAGS

.qd.TYPES

.qd.doc

.qd.docws

Documentation generator for q (`.qd`)