<commit_before>q-doc
=====

> Code documentation generator for kdb 

This repository is currently a WIP. Feel free to look around. I'll put some more details here once it's done.<commit_msg>README: Start defining the q-doc method<commit_after>q-doc
=====

> Code documentation generator for kdb 

This repo provides a method of writing function comments in a machine readable way along with a parser and HTML viewer of the generated documentation. 

The commenting method, along with the associated parser, is known as `q-doc`.

### Documenting Code

In order to use this documentation generator, your function comments must confirm to the schema defined in this section.

#### Method

1. Only comments preceding a function (or constant) declaration will be parsed.
   * All comments within functions will be *ignored*.
2. All q-doc comment lines should be start with a single forward slash ("/").
3. A description of the function must be the first part of the comment body. It can span 1 or more lines
4. The tags below are supported by the parser. All are optional.
   * `@param` : Describes the function's input parameters
   * `@returns` : Describes the function's return value
   * `@throws` : Describes each exception that can be thrown by the function
   * `@see` : Provides references to other functions that are used within the function

#### Examples
{'fraction_non_alphanumeric': 0.0661764705882353, 'fraction_numerical': 0.003676470588235294, 'mean_word_length': 4.15530303030303, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3413597', 'n_tokens_mistral': 345, 'n_tokens_neox': 329, 'n_words': 197}