Documentation

This guide provides documentation standards for XRC Toolkit packages, ensuring consistent documentation across the entire collection of packages.

XRC Toolkit developers should create package documentation as follows: 1. Add comments in the code itself, as XML comments, see details below. 2. Maintain package.json in the package root directory. This file should contain up-to-date information about the package. 3. Update images in the Documentation~/images directory, such as component screenshots, as needed. 3. Maintain CHANGELOG.md in the package root directory. This file should contain up-to-date information on the changes made to the package for each release.

By following these guidelines, the package website, including the manual and scripting API, will be updated automatically by the GitHub Actions workflow.

XML Documentation Standards

Overview

See Microsoft's XML documentation guidelines for getting started with XML comments in C#.

XML documentation comments serve multiple purposes in XRC Toolkit packages:

1. API documentation generation: DocFX uses XML comments to generate package documentation
2. Code maintenance: Well-documented code is easier to understand, debug, and extend
3. Package integration: Clear documentation helps developers integrate packages correctly
4. Unity Inspector guidance: Tooltips and help text for developers using components

Documentation Requirements

• All public members must have XML documentation
• Complex private members should have regular comments, not XML comments

Class Documentation

Document class purpose, architecture pattern, and usage:

/// <summary>
/// This component contains the main logic for the selection technique.
/// It holds a reference to an interactor responsible for selecting the object of interest.
/// The component modifies the interactor's attach transform, as well as its collider, based on the component's properties.
/// </summary>
/// <remarks>
/// This component uses composition to modify and add features to the referenced interactor.
/// </remarks>
public class SphereSelectLogic : MonoBehaviour

Method Documentation

Provide comprehensive descriptions including behavior details:

/// <summary>
/// Sets the radius of the sphere. The radius is clamped based on <see cref="minRadius"/> and <see cref="maxRadius"/>.
/// This method updates the radius and center of <see cref="interactor"/>'s Sphere Collider, as well as the local position for <see cref="interactor"/>'s attach transform.
/// If the <see cref="radius"/> is smaller than <see cref="defaultRadius"/>, then the sphere center is shifted accordingly away from the <see cref="defaultCenter"/>, so the left edge of the sphere stays fixed during resizing until it reaches the default radius value. This behavior is identical to the Gravity Sketch application.
/// If the <see cref="radius"/> is equal to or larger than <see cref="defaultRadius"/>, then the sphere's center is set to <see cref="defaultCenter"/>.
/// </summary>
/// <param name="radiusValue">The value to be assigned to the sphere radius</param>
public void SetRadius(float radiusValue)

Property Documentation

Include clear descriptions, usage patterns, and inspector behavior:

/// <summary>
/// The interactor responsible for selecting an object.
/// If the interactor reference is not assigned in the inspector, the component will search for an interactor on the same game object.
/// </summary>
public XRDirectInteractor interactor
{
    get => m_Interactor;
    set => m_Interactor = value;
}

/// <summary>
/// The minimum radius of the sphere.
/// </summary>
public float minRadius
{
    get => m_MinRadius;
    set => m_MinRadius = value;
}

Serialized Field Documentation

Private serialized fields should not contain XML comments. Instead, their associated public property should contain the XML comments. For the serialized field, provide Unity inspector tooltips and behavior explanation:

[SerializeField]
[Tooltip("The Input Action that will be used to resize the sphere")]
private InputActionProperty m_ChangeRadius;

/// <summary>
/// The input action property associated with changing the radius of the of sphere.
/// </summary>
public InputActionProperty changeRadiusAction
{
    get => m_ChangeRadius;
    set => m_ChangeRadius = value;
}

Cross-References

Use <see cref=""/> extensively for related members:

/// <summary>
/// The default radius value when starting the application.
/// </summary>
/// <remarks>
/// See <see cref="SetRadius"/> for explanation on how <see cref="defaultRadius"/> and <see cref="defaultCenter"/> determine the sphere's center when given an input radius value.
/// </remarks>
public float defaultRadius
{
    get => m_DefaultRadius;
    set => m_DefaultRadius = value;
}