cyberpresidentvanellope/Paradise
1
0
Fork 0
mirror of https://github.com/ParadiseSS13/Paradise.git synced 2026-07-20 19:44:09 +01:00
Code Issues Packages Projects Releases Wiki Activity

vocab: class -> type (#28289)

Browse Source
This commit is contained in:
chuga-git
2025-02-09 03:20:59 -06:00
committed by GitHub
parent efdb19ac7e
commit e5f91c1993
1 changed files with 22 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/references/autodoc.md
+22 -22
View File
@@ -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]`.