-
Notifications
You must be signed in to change notification settings - Fork 42
Class Documentation
Jennifer Maxwell edited this page Aug 20, 2019
·
7 revisions
An increasing portion of the isetbio code base is in the form of classes. This page covers documentation guidelines for these.
See Documentation & Formatting for links to documentation for other code types (functions, tutorials, etc.)
We've adopted certain formatting and style guidelines for the header comment for classes within the ISETBIO scope. The header comment has both required and optional headings. We also try to include a short, fully executable example of how to initiate the class in block comments at the top of the source code. These examples are placed in an optional Examples section of the code after the required headings. Since the developers often return to view these examples, which may be selected and executed from the Command Window in the MATLAB editor, we believe they are useful and should be included when possible. Body text in the required headings's Description section should indicate whether the code contains such examples.
These headings and their content are intended to clarify the purpose of the class, and how to implement and use it.
- Short Description - This is a one-line (<75 character) quick summary of the class's general purpose
- Syntax - Show an example usage of the class initialization call. Body text is indented 3 spaces from the comment marker
- Description - A detailed description of the class, its intended uses, etc. Body text is indented 4 spaces from the comment marker for first-level.
- Inputs - A list of all of the required inputs for the class, as well as explanations to what they represent. The line items are indented a minimum of 4 spaces from the comment marker. The definitions are separated from their names by a dash, and the left margin of the text is aligned for all definitions based off the length of all of the input/output/optional variables, with few exceptions. The definitions are required even if you feel the variable name makes the input's definition obvious.
- Outputs - A list of all of the outputs of the class, as well as explanations to what they represent. The line items are indented a minimum of 4 spaces from the comment marker. The definitions are separated from their names by a dash, and the left margin of the text is aligned for all definitions based off the length of all of the input/output/optional variables, with few exceptions. The definitions are required even if you feel that the variable name makes the output's definition obvious.
- Optional key/value pairs - This section is for optional variables and/or key/value pairs, and follows the same guidelines as the inputs and outputs sections (4 spaces indented, etc...). If there are no pairs, use "None." please. The keys will be encapsulated in single quotes and the explanation of the keys should contain the expected value's type. e.g. 'myKey' - String describing what the key unlocks. Possible values are 'house', 'office', 'garage'. Default is 'house'
Example header comment with the required headings:
classdef coneMosaicHex < coneMosaic
% Create a hexagonal cone mosaic class
%
% Syntax:
% cMosaicHex = coneMosaicHex(resamplingFactor, [varargin]);
%
% Description:
% The cone mosaic HEX is a subclass of coneMosaic. It differs because
% the array of cones is placed on a hexagonal, rather than rectangular,
% grid.
%
% The hex mosaic is sampled according to the provided resamplingFactor.
% The cone density can be spatially-varying if eccBasedConeDensity is
% set to true.
%
% The customLambda argument is empty to obtain default performance, but
% may be set to set the spacing for regularly spaced hexagonal mosaics.
% The units of customLambda are microns
%
% The code below contains examples of class usage. To access these
% examples, type 'edit coneMosaicHex.m' into the Command Window.
%
% Inputs:
% resamplingFactor - Integer. The grid resampling factor.
%
% Outputs:
% cMosaicHex - Object. The created cone mosaic hex object.
%
% Optional key/value pairs:
% Some of the possible key/value pairs are listed below:
% 'eccBasedConeDensity' - Boolean. Variable indicating whether or not to
% use the eccentricity-based cone density.
% Default False.
% 'customLambda' - Double. Custom micron cone spacing distance.
% Default is [].
% 'customInnerSegmentDiameter'
% - Double. Custom diameter for the inner segment.
% Default is pigment.pdWidth from super class.
%
end
Several of the classes have an extensive set of examples of actual functioning uses of the class. Examples are encapsulated in block comments, as shown below where we illustrate the format of the Optional Headings. Written using this block comment format, the examples can be run by a copy-and-paste directly from the code.
The Examples section is separated from the rest of the sections by a preceding blank line. For this reason, the Examples do not show up immediately in help or doc calls. We made this decision because the examples can be lengthy and not all of them are immediately helpful to the function's significance.
Examples are the last section of a heading, always, and are removed from previous sections by a preceding blank like. Each example is encased in a set of block comments %{ %}. No text can be on either the opening or closing lines.
Please remember to comment at the end of the Required Headings's Description (see above) that there are examples, if there are.
These headings are nice to have, but not required.
- References - This section is for citations. Links and titles are very useful, and possibly more thorough explanations if you feel you cannot adequately cover everything in the description section. Aside from being 4 spaces indented from the comment marker, we have not established anything too restrictive about formatting for this section
- Notes - This is one location to list known issues, complications, or shortcomings of existing code. It is also a good place to record TODO lists. This section is typically composed of a bulleted list that is denoted by a comment marker, 4 spaces, and then an asterisk. Notes about function details and existing usage should be kept in the description section. We also try to include the initials of the person who wrote the note.
- History - This section records a running change of who edited your file, when, and with a small summary of the changes made. The format is The comment marker, 4 spaces, the date in MM/DD/YY, two spaces, the initial(s) of the editors, two spaces, and the change summary. This section is also separated from the rest of the header like the examples section (with a line of white space). This section would be placed before the examples section.
- See Also - This section is for references to other MATLAB functions/classes by name. The spacing for this section is 3 spaces after the comment marker. This would be the final section in the main body of the header.
An example header comment including optional headings:
classdef coneMosaicHex < coneMosaic
% Create a hexagonal cone mosaic class
%
% Syntax:
% cMosaicHex = coneMosaicHex(resamplingFactor, [varargin]);
%
% Description:
% The cone mosaic HEX is a subclass of coneMosaic. It differs because
% the array of cones is placed on a hexagonal, rather than rectangular,
% grid.
%
% The hex mosaic is sampled according to the provided resamplingFactor.
% The cone density can be spatially-varying if eccBasedConeDensity is
% set to true.
%
% The customLambda argument is empty to obtain default performance, but
% may be set to set the spacing for regularly spaced hexagonal mosaics.
% The units of customLambda are microns
%
% The code below contains examples of class usage. To access these
% examples, type 'edit coneMosaicHex.m' into the Command Window.
%
% Inputs:
% resamplingFactor - Integer. The grid resampling factor.
%
% Outputs:
% cMosaicHex - Object. The created cone mosaic hex object.
%
% Optional key/value pairs:
% Some of the possible key/value pairs are listed below:
% 'eccBasedConeDensity' - Boolean. Variable indicating whether or not to
% use the eccentricity-based cone density.
% Default False.
% 'customLambda' - Double. Custom micron cone spacing distance.
% Default is [].
% 'customInnerSegmentDiameter'
% - Double. Custom diameter for the inner segment.
% Default is pigment.pdWidth from super class.
%
% See Also:
% CONEMOSAIC, t_coneMosaicHex, t_coneMosaicHexReg
%
% History:
% xx/xx/16 NPC ISETBIO Team, 2016
% 02/21/18 jnm Formatting
% 04/16/18 jnm Move resamplingFactor to Inputs section as it is
% required, and not optional based on response when
% attempting to instantiate a coneMosaicHex.
% Examples:
%{
resamplingFactor = 8;
eccBasedConeDensity = true;
customLambda = 3.0;
% If not passed (or set to []) @coneMosaiHex chooses the cone spacing
% based on the eccentricity of the mosaic as determined by the
% coneSizeReadData function. If set to a value (specified in microns),
% cone spacing is set to that value. Note that if the
% 'eccBasedConeDensity' param is set to true, the 'customLambda' param
% is ignored.
customInnerSegmentDiameter = 2.5;
% If not passed (or set to []) @coneMosaiHex chooses the default
% pigment.pdWidth, pigment.pdHeight values from its superclass. If it
% set to a value (specified in microns) @coneMosaicHex sets
% pigment.pdWidth and pigment.pdheight to
% squareSizeFromCircularAperture(...
% customInnerSegmentDiameter).
cMosaicHex = coneMosaicHex(resamplingFactor, ...
'name', 'the hex mosaic', ...
'fovDegs', 0.35, ...
'eccBasedConeDensity', eccBasedConeDensity, ...
'noiseFlag', 'none', ...
'spatialDensity', [0 0.6 0.3 0.1], ...
'maxGridAdjustmentIterations', 100);
cMosaicHex.window;
%}
end
- General:
- Line length is capped at 75 characters.
- All section headers are one space offset from the comment marker, and with the exception of the Optional key/value pairs section, follow Title casing. (First letter of all words is capitalized).
- Required Sections:
- Short description has no header, is one space offset from comment marker
- Syntax body text is 3 spaces offset from comment marker
- Description body text is 4 spaces offset from comment marker
- Inputs, typically an unmarked list, with the body text is 4 spaces offset from comment marker. Left align variable descriptions based on length of longest variable name. Specify what the input is (string, row vector, matrix, etc.). If the input is optional provide the default value.
- Outputs, typically an unmarked list, with the body text is 4 spaces offset from comment marker. Left align variable descriptions based on length of longest variable name. Specify what the output is (string, row vector, matrix, etc.)
- Optional key/value pairs are typically an unmarked list, with the body text is 4 spaces offset from comment marker. Left align variable descriptions based on length of longest variable name. For values, specify what it is (string, row vector, matrix, etc.) and provide default value.
- Optional Sections:
- References body text is 4 spaces offset from comment marker
- Notes, typically a bulleted list, with the asterisk marker 4 spaces offset from comment marker. The Text is one space offset from that. Individual notes follow the format [Note: XXX - Body] where XXX are the initials of the note's author and Body is the body text of the notes.
- See Also body text is 4 spaces offset from comment marker
- History has dates in the format MM/DD/YY offset from the comment marker by 4 spaces, then commenting individual's initials offset by 2 spaces, and the body of the change summary offset by an additional 2 spaces.
In addition to the heading, there are formatting specifications associated with the body text of a class.
- General:
- Line length is capped at 75 characters.
- All comments are at minimum one space offset from the comment marker.
- Properties - Property comments should conform to the following style:
- Should be immediately above the property
- Property name should be one space offset from comment marker, and in lowerCamelCase
- Line with property name should contain a short description (maintain line length constraints) offset from property name by a spaced dash ' - '
- Additional information or a longer description if desired, is included in subsequent lines, indented from the comment marker by three spaces. This is visible for if a user requests 'help <class>.<property>', such as 'help coneMosaicHex.marginF'
Example of correctly-formatted properties, from the private coneHexMosaic properties.
% resamplingFactor - The resampling factor.
resamplingFactor
% marginF - Factor determining how much more mosaic to compute.
% more (if > 1) or less (if < 1).
marginF
% sConeMinDistanceFactor - min distance between neighboring S-cones
% This will make the S-cone lattice semi-regular
% min dist = f * local cone separation.
sConeMinDistanceFactor
- Methods & Embedded Functions
- The constructor should be commented as if it was a function.
- Method/function declarations should have a short description immediately preceding them. This is primarily for ease of reading the code itself. Calling 'help <class>.<function>' will return information from the header comment of the implementation of the function if available (which it should be). An example is 'help coneHexMosaic.displayInfo'
- Embedded functions (that is functions that are implemented in the same file as the constructor) should be commented in the same fashion as standalone functions, and follow all of the codes and conventions described in Function Documentation
Example of formatted declaration.
% Visualize different aspects of the hex grid
hFig = visualizeGrid(obj, varargin);