diff --git a/docs/references/autodoc.md b/docs/references/autodoc.md index bb1278becf86..3eff9a7501fe 100644 --- a/docs/references/autodoc.md +++ b/docs/references/autodoc.md @@ -17,33 +17,33 @@ reference. [dmdoc]: https://github.com/SpaceManiac/SpacemanDMM/tree/master/crates/dmdoc ## Documenting Code On Paradise -We use block comments to document procs and classes, and we use `///` line +We use block comments to document procs and types, and we use `///` line comments when documenting individual variables. Documentation is not required at Paradise, but it is highly recommended that all new code be covered with DMdoc code, according to the [Specifications](#specification). -We also recommend that when you touch older code, you document the functions that you +We also recommend that when you touch older code, you document the procs that you have touched in the process of updating that code ### Specification -A class *should* always be auto-documented, and all public functions *should* be +A type *should* always be auto-documented, and all public procs *should* be documented. -All class level defined variables *should* be documented. +All type level defined variables *should* be documented. -Internal functions *can* be documented, but may not be. +Internal procs *can* 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. +A public proc is any function that a developer might reasonably call while using +or interacting with your object. Internal procs are helper functions that your +public procs 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 +the proc to jump to its definition ```dm /** @@ -57,36 +57,36 @@ the proc to jump to it's definition */ ``` -### Documenting Classes -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 one-line description of the class. Finally we give a longer -multi paragraph description of the class and it's details. +### Documenting types +We first give the name of the type as a header, this can be omitted if the name +is just going to be the typepath of the type, as dmdoc uses that by default. +Then we give a short one-line description of the type. Finally we give a longer +multi paragraph description of the type and its details. ```dm /** - * # Classname (Can be omitted if it's just going to be the typepath) + * # type name (Can be omitted if it's just going to be the typepath) * * The short overview * * A longer - * paragraph of functionality about the class + * paragraph of functionality about the type * 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. +Give a short explanation of what the variable, in the context of the type, or define is. ```dm -/// Type path of item to go in suit slot +/// Typepath 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. +where you don't want to be tied to the formal layout of the type structure. On Paradise 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 @@ -98,10 +98,10 @@ You can use certain special template variables in DM DOC comments and they will be expanded. - `[DEFINE_NAME]` expands to a link to the define definition if documented. -- `[/mob]` expands to a link to the docs for the /mob class. -- `[/mob/proc/Dizzy]` expands to a link that will take you to the /mob class and +- `[/mob]` expands to a link to the docs for the /mob type. +- `[/mob/proc/Dizzy]` expands to a link that will take you to the /mob type and anchor you to the dizzy proc docs. -- `[/mob/var/stat]` expands to a link that will take you to the /mob class and +- `[/mob/var/stat]` expands to a link that will take you to the /mob type and anchor you to the stat var docs You can customise the link name by using `[link name][link shorthand]`.