# 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


## 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
"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 overviewarg!fileoverviewparam] :/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, 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

// a part of the 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 AAPLGOOGMSFTAMZN
// /=> "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


### 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:

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: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                          |


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 ab!(1; "x") Key value type specifier dict (a:long; b:char)
enum (ab)?(abba) 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:

### 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
boolbooleanbytecharcharacterdatedatetimefloatguidintintegerlongminutemonthrealsecondshortstringsymboltimetimespantimestamp

// 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 descriptionarg!fileoverviewparam]  .

// 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[docprivatedoctododocempty!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: functionfunctionfunctiondatafilefile;
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