Related Jira Issues

https://unity3d.atlassian.net/browse/FNSDKEXT-83

Introduction

The following documentation defines the means by which code will be commented and the types of documentation that will be produced. It should be noted that the https://unity3d.atlassian.net/wiki/spaces/FNUPEXT/pages/1584332803 contains its own guide to general commenting practice. Should this document and the Style Guide conflict when it pertains to commenting code, this document will take precedence. Please notify the Project Lead of any discrepancies between this document and the Style Guide so that they may be addressed.

Comments

Classes

• When building a class for the FN SDK, a <summary> tag will be written to describe the general purpose of the class.
  
  

  /// <summary> /// This is an example of a summary tag /// </summary> public class ExampleClass {}

   

  • Should additional information be needed to describe a class beyond a general purpose (for instance, possible use cases or items to keep in mind when using the class, a <remarks> tag will be used to avoid an overly verbose summary
    
    

    /// <summary> /// This is a brief summary /// </summary> /// <remarks> /// This is a lot more text that is acceptable within the confines of a remarks class. /// Here is another line of text for good measure /// And why not, here's a third line of text /// </remarks> public class ComplicatedClass {}

  • Should the class inherit from another class or implement an interface, a <see> tag will be use to link generated documentation to the appropriate base class/interface
    
    

    /// <summary> /// This is an example of a derived class with a see tag. /// <see cref="ExampleClass"/> /// </summary> public class DerivedExampleClass : ExampleClass {}

Methods

• When building a public method:

  • A <summary> tag will be written to describe the purpose for the method

  • A <param> tag will be written to describe each parameter within the public function
    
    

  • A <returns> tag will be used to describe the return value of the method where applicable

    • Use common language when describing return values.
      

   

• When building a private method, no <summary> tagged comment is required. However, it is highly recommended that a general, non-xml tag be at least written to describe the nature of a private method should it’s purpose not be immediately apparent.

• If a method (public or private) can throw an exception, the exception tag will be used to document what types of exceptions the method can be expected to throw
  
  

Enumerations

• Enumerations will have a general comment to describe the general purpose of the enumerations as a whole

Miscellaneous

While example code itself is not required, should example code be included, an <example> and <code> block should be used.

Documentation

• Any public facing classes will have an associated Class Diagram to outline its general makeup

• Public facing classes within the Communications API will have sequence diagrams built to outline the general flow of communication between the device and the SDK

• Documentation describing the general usage of the SDK will be provided

• Documentation describing the makeup of the Unity example scene will be provided

• Documentation describing how users can make use of the VictoR SDK Unity package will be provided

• Documentation generated from the xmldoc comments will be provided

• Code samples will be written to assist users with familiarizing themselves with the SDK