Skip to content

qdoc - Documentation generator for q

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:

  1. A function item .foo.add that takes two arguments x and y of type long and returns the sum as an integer

  2. 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
@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
{[]
    }

Category

Syntax

@category CATEGORY_NAME

Overview

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

See qdoc output for information on default category

Examples

Set the category of the function to Foo

// @category Foo
{[]
    }

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 and return tag to add descriptions for table column or dictionary keys.

Examples

Documents the description for the keys of a dictionary parameter

// @param   foo     {dict (x: int; y: char)}   Parameter description
// @desc    foo.x   Description of key x
// @desc    foo.y   Description of key y
{[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
{[]
    }

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 documented by default, but the behavior can be changed by unsetting 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. 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:

  1. Basic typedefs: Typedefs that accepts no arguments
  2. 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 secondType  {dict (a: int; b: char)} This is my second type.
    }

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
newParam2.b char

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"&#36;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:

1. 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[]

2. 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[]

3. 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.

  • Files: A symbolic path to a q file. You can also specify the path to a directory or list each \*.q, \*.README and \*.README.md files separately.
  • Items: A table of
    1. name: Symbolic name of the items including their namespace/context. E.g.: .foo.bar
    2. kind: Symbolic type of the items. Could be one of `function`, `data`, `readme`
    3. content: String contents of the items.

The generated Markdown files are written to ./out/md directory by default.

Parameter(s):

Name Type Description
settings dict Optional Argument. Pass empty dictionary to use default settings
settings.out symbol Path to store generated documentation. Default is ./out
settings.preprocessors symbol[] Specifies the preprocessors you want to run. Options are FILE, FUNCTION, README. Default is all.
settings.tagmap dict Use a non-default tag name, i.e. `parameter`description!`param`fileoverview`
settings.tagmap.<symbol> symbol Repeatable;
settings.group symbol Specifies grouping in Markdown files. Options are category and subcategory. Default is category.
settings.exclude string | (symbol; string) Specifies a regex expression indicating items to exclude.
settings.docprivate boolean Specifies whether to include items with an @private tag. Default is false.
settings.docempty boolean Specifies whether to include items that have no qdoc tags. Default is false.
settings.doctodo boolean Specifies whether to include items that have @todo tags. Default is false.
settings.recursive boolean Specifies whether to recurse subdirectories looking for q scripts and README.md files. Default is true.
settings.write boolean Specifies whether to write the generated Markdown files to disk. Default is true.
src (symbol | table ([] name: symbol; kind: symbol; content: string)) Source of the data to be documented There are two src options: q files on disk or a table of items. See the overview above for more information

Returns:

Name Type Description
output dict A dictionary of path to the output directory (MD files), Markdown content in each file and the table of errors
output.out hsym The directory where the generated Markdown files are written on disk
output.md table A table of items and their generated Markdown content
output.md.file symbol Name of the Markdown file where the item resides
output.md.name symbol Name of the item
output.md.kind symbol Type of the item
output.md.module symbol The module the item belongs to
output.md.category symbol The category the item belongs to
output.md.subcategory symbol The subcategory the item belongs to
output.md.content string Markdown content of the item
output.error table A table of errors encountered during Markdown generation
output.error.ref symbol Name of the item
output.error.qdType string The documented qdoc type
output.error.errorType symbol The type of error (PARSE or RESOLUTION)
output.error.error string The error message

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(s):

Name Type Description
x any

Throws:

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

See Also: .qd.doc