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 argumentsx
andy
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 thekind
tag. Multiple readmes for different namespaces can be included within a single q file by starting and ending each readme comment block withkind
andend
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
anddefault-subcategory
tags in theonLoad
function - defined on per item basis using the
category
andsubcategory
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 anonLoad
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
, 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