<commit_before># dmdoc
[DOCUMENTATION]: https://codedocs.yogstation.net

[BYOND]: https://secure.byond.com/

[DMDOC]: https://github.com/SpaceManiac/SpacemanDMM/tree/master/src/dmdoc

[DMDOC] is a documentation generator for DreamMaker, the scripting language
of the [BYOND] game engine. It produces simple static HTML files based on
documented files, macros, types, procs, and vars.

We use **dmdoc** to generate [DOCUMENTATION] for our code, and that documentation
is automatically generated and built on every new commit to the master branch

This gives new developers a clickable reference [DOCUMENTATION] they can browse to better help
gain understanding of the /tg/station codebase structure and api reference.

## Documenting code on yogstation
We use block comments to document procs and classes, and we use `///` line comments
when documenting individual variables.

It is required that all new code be covered with DMdoc code, according to the [Requirements](#Required)

We also require that when you touch older code, you must document the functions that you
have touched in the process of updating that code

### Required
A class *must* always be autodocumented, and all public functions *must* be documented

All class level defined variables *must* be documented

Internal functions *should* be documented, but may not be

A public function is any function that a developer might reasonably call while using
or interacting with your object. Internal functions are helper functions that your
public functions rely on to implement logic


### Documenting a proc
When documenting a proc, we give a short one line description (as this is shown
next to the proc definition in the list of all procs for a type or global
namespace), then a longer paragraph which will be shown when the user clicks on
the proc to jump to it's definition
```
/**
  * Short description of the proc
  *
  * Longer detailed paragraph about the proc
  * including any relevant detail
  * Arguments:
  * * arg1 - Relevance of this argument
  * * arg2 - Relevance of this argument
  */
```

### Documenting a class
We first give the name of the class as a header, this can be omitted if the name is
just going to be the typepath of the class, as dmdoc uses that by default

Then we give a short oneline description of the class

Finally we give a longer multi paragraph description of the class and it's details
```
/**
  * # Classname (Can be omitted if it's just going to be the typepath)
  *
  * The short overview
  *
  * A longer
  * paragraph of functionality about the class
  * including any assumptions/special cases
  *
  */
```

### Documenting a variable/define
Give a short explanation of what the variable, in the context of the class, or define is. 
```
/// Type path of item to go in suit slot
var/suit = null
```

## Module level description of code
Modules are the best way to describe the structure/intent of a package of code
where you don't want to be tied to the formal layout of the class structure.

On /tg/station we do this by adding markdown files inside the `code` directory
that will also be rendered and added to the modules tree. The structure for
these is deliberately not defined, so you can be as freeform and as wheeling as
you would like.

[Here is a representative example of what you might write](https://codedocs.yogstation.net/datum/callback.html)

## Special variables
You can use certain special template variables in DM DOC comments and they will be expanded
```<commit_msg>We didnt steal this<commit_after># dmdoc
[DOCUMENTATION]: https://codedocs.yogstation.net

[BYOND]: https://secure.byond.com/

[DMDOC]: https://github.com/SpaceManiac/SpacemanDMM/tree/master/src/dmdoc

[DMDOC] is a documentation generator for DreamMaker, the scripting language
of the [BYOND] game engine. It produces simple static HTML files based on
documented files, macros, types, procs, and vars.

We use **dmdoc** to generate [DOCUMENTATION] for our code, and that documentation
is automatically generated and built on every new commit to the master branch

This gives new developers a clickable reference [DOCUMENTATION] they can browse to better help
gain understanding of the yogstation codebase structure and api reference.

## Documenting code on yogstation
We use block comments to document procs and classes, and we use `///` line comments
when documenting individual variables.

It is required that all new code be covered with DMdoc code, according to the [Requirements](#Required)

We also require that when you touch older code, you must document the functions that you
have touched in the process of updating that code

### Required
A class *must* always be autodocumented, and all public functions *must* be documented

All class level defined variables *must* be documented

Internal functions *should* be documented, but may not be

A public function is any function that a developer might reasonably call while using
or interacting with your object. Internal functions are helper functions that your
public functions rely on to implement logic


### Documenting a proc
When documenting a proc, we give a short one line description (as this is shown
next to the proc definition in the list of all procs for a type or global
namespace), then a longer paragraph which will be shown when the user clicks on
the proc to jump to it's definition
```
/**
  * Short description of the proc
  *
  * Longer detailed paragraph about the proc
  * including any relevant detail
  * Arguments:
  * * arg1 - Relevance of this argument
  * * arg2 - Relevance of this argument
  */
```

### Documenting a class
We first give the name of the class as a header, this can be omitted if the name is
just going to be the typepath of the class, as dmdoc uses that by default

Then we give a short oneline description of the class

Finally we give a longer multi paragraph description of the class and it's details
```
/**
  * # Classname (Can be omitted if it's just going to be the typepath)
  *
  * The short overview
  *
  * A longer
  * paragraph of functionality about the class
  * including any assumptions/special cases
  *
  */
```

### Documenting a variable/define
Give a short explanation of what the variable, in the context of the class, or define is. 
```
/// Type path of item to go in suit slot
var/suit = null
```

## Module level description of code
Modules are the best way to describe the structure/intent of a package of code
where you don't want to be tied to the formal layout of the class structure.

On yogstation we do this by adding markdown files inside the `code` directory
that will also be rendered and added to the modules tree. The structure for
these is deliberately not defined, so you can be as freeform and as wheeling as
you would like.

[Here is a representative example of what you might write](https://codedocs.yogstation.net/datum/callback.html)

## Special variables
You can use certain special template variables in DM DOC comments and they will be expanded
```
{'fraction_non_alphanumeric': 0.05511136493432325, 'fraction_numerical': 0.0005711022272986865, 'mean_word_length': 4.212053571428571, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 8, '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': '627280', 'n_tokens_mistral': 1825, 'n_tokens_neox': 1747, 'n_words': 1045}