Class documentation

• General information
• GBX.NET.Engines namespace documentation
  • Classes
  • Chunks
• Markdown pages

Documentation has become a crucial topic of GBX.NET due to its increasing codebase. This article will be a brief overview of how the documentation process works.

Adding attributes to classes and properties is part of implementing the automated documentation, but this article does not cover the topic.

General information

• Ideally, every public class, method, and property should be documented with the XML comments. Because GBX.NET is a large project, this may take some time.
• The <exception> XML tag should be used to document exceptions that are thrown by the method. The methods calling that method should follow on with the <exception> tag chain (including its content message), so that it's clear all these exceptions can throw. Using a good .NET IDE should make this easier. If the method is protecting the exception that can throw, that exception should not be included in the XML tags, obviously.
• If you're referencing a class or a property, use the <see> tag.

GBX.NET.Engines namespace documentation

This chapter describes the documentation rules to follow in the GBX.NET.Engines namespace.

Classes

Classes of the GBX.NET.Engines namespace that are not nested in other classes.

Summary (optional)

An explanation of the class (its purpose, etc.), preferably meaningful.

/// <summary>
/// [explanation]
/// </summary>

Example

• Context: CGameCtnMediaBlockDOF
• [explanation] = MediaTracker block - Depth of field

/// <summary>
/// MediaTracker block - Depth of field
/// </summary>

Remarks

/// <remarks>ID: [class ID in hex on 8 digits]</remarks>

Example

• Context: CGameCtnChallenge
• [class ID in hex] = 0x03043000

/// <remarks>ID: 0x03043000</remarks>

Regions

Regions are controversial, but they have been utilized in this project to keep the folders clean from chunk classes. The idea of a chunk being a nested class of the main class appeared to be the cleanest solution that is also the closest to how the engine works. The folders would have hundreds (maybe thousands) of files if all of the nested chunk classes were disjoined into their own files.

Because auto-properties cannot be used due to the ref keyword, and because some properties require to discover the associated chunks first, the region pattern was applied fully, but only in the engine classes.

Inside the class, the region pattern is applied like this:

#region Enums

#endregion

#region Constants

#endregion

#region Fields

#endregion

#region Properties

#endregion

#region Constructors

#endregion

#region Chunks

#endregion

#region Other classes

#endregion

Only the regions that have members for them are used.

Other classes are better to separate into their own files.

Fields

Fields are not documented - they're always private.

Properties

Properties should be documented to be easy to understand according to General information (if the meanings of them are known).

Constructors

Constructors are not documented - they are forced to be non-public (for the time being).

Methods

Methods should be documented to be easy to understand according to General information.

Chunks

Chunk classes that are nested inside engine classes.

Regions

Regions are, once again, controversial, but they have been utilized to keep the folders clean from chunk classes. To easily see what chunks mean what, the following region is wrapped around the chunk class:

#region [last 3 digits of chunk ID in hex] [type of chunk if special] chunk [optional description in brackets]

#endregion

Examples

• Context: CGameCtnChallenge.Chunk03043007 chunk class
• [last 3 digits of chunk ID in hex] = 0x007
• [type of chunk if special] = header
• [optional description in brackets] = thumbnail

#region 0x007 header chunk (thumbnail)

#endregion

• Context: CGameCtnAnchoredObject.Chunk03101004 chunk class
• [last 3 digits of chunk ID in hex] = 0x004
• [type of chunk if special] = skippable
• [optional description in brackets] = none

#region 0x004 skippable chunk

#endregion

• Context: CGameCtnReplayRecord.Chunk03093002B chunk class
• [last 3 digits of chunk ID in hex] = 0x002
• [type of chunk if special] = unskippable
• [optional description in brackets] = track

#region 0x002 chunk (track)

#endregion

Summary

Summary has similar content to region title, except it also adds the engine class name in front:

/// <summary>
/// [engine/parent class name] [last 3 digits of chunk ID in hex] [type of chunk if special] chunk [optional description in brackets]
/// </summary>

Examples

• Context: CGameCtnChallenge.Chunk03043007 chunk class
• [engine/parent class name] = CGameCtnChallenge
• [last 3 digits of chunk ID in hex] = 0x007
• [type of chunk if special] = header
• [optional description in brackets] = thumbnail

/// <summary>
/// CGameCtnChallenge 0x007 header chunk (thumbnail)
/// </summary>

• Context: CGameCtnAnchoredObject.Chunk03101004 chunk class
• [engine/parent class name] = CGameCtnAnchoredObject
• [last 3 digits of chunk ID in hex] = 0x004
• [type of chunk if special] = skippable
• [optional description in brackets] = none

/// <summary>
/// CGameCtnAnchoredObject 0x004 skippable chunk
/// </summary>

• Context: CGameCtnReplayRecord.Chunk03093002B chunk class
• [engine/parent class name] = CGameCtnReplayRecord
• [last 3 digits of chunk ID in hex] = 0x002
• [type of chunk if special] = unskippable
• [optional description in brackets] = track

/// <summary>
/// CGameCtnReplayRecord 0x002 chunk (track)
/// </summary>

That's all the documentation rules for now

More to be specified later 👀