Guide to SpacemanDMM Docblocks

SpacemanDMM, one of our recommended plugins for Visual Studio Code, includes a feature called dmdoc that lets VSC parse 'docblocks', or blocks of documentation. This results in these documentation blocks appearing whenever you hover over a reference to a var, proc, or essentially anything (Except defines, those are special snowflakes that don't parse correctly) anywhere in the code.

Here's an example of what a parsed docblock looks like in VSC, and the code that generated it:

/**
 * Damage's the atom's health by the given value.
 * If using the `damage_sources` extension subtype, will apply damage to the given damage type.
 * Override only for modifying damage. Do not override to apply additional effects - Use `post_damage_health()` instead.
 */
/atom/proc/damage_health(damage, damage_type = null)

See SpacemanDMM dmdoc documentation for specifics.

Applying docblocks in Baystation12

We heavily encourage commenting code but don't explicitly require it in reviews except in special cases. However, if you do provide commenting for your code, we'll be requesting you follow the docblock standard for any code specific to var/, proc/, and other definitions. There are multiple ways to define a docblock according to SpacemanDMM's documentation, however, for consistency, we'll be focusing on only 2 methods - A single line method and a multi-line method.

Single-Line Docblocks

If your comment for a definition will only consist of a single line, then you can provide it as a single-line comment. These comments should be entered on the line directly above the definition being commented, and prefixed with 3 slashes instead of 2 - ///:

/// Whether or not the atom should use the health handler when initialized.
var/use_health_handler = FALSE

Multi-Line Docblocks

If your comment will consist of multiple lines or is particularly long and you want to break it up into multiple lines in the code, use the multi-line format instead. This will be wrapped in an opening /** and a closing */, both on separate lines, with each line of the docblock prefixed by *. These blocks should also be on the line directly above the item being defined:

/**
 * Initialization config for the health handler.
 *
 * `max_health` - Default maximum health.
 *
 * `resist_*` - Resistance multiplier for various damage types, where `*` is replaced by the damage type's string value.
 *
 * `min_damage` - Minimum threshold to damage the atom.
 */
var/list/health_handler_config = list(
	"max_health" = 100
)