Tutorial Documentation

Introduction

There are a large number of tutorials for nearly all of the isetbio components. This page covers documentation guidelines for the script-written tutorials and leverages the Functions documentation for tutorials of that style.

See Documentation & Formatting for links to documentation for other code types (functions, classes, etc.)

We've adopted certain formatting and style guidelines for the header comment for tutorials within the ISETBIO scope. The header comment has both required and optional headings. Since the developers often view these tutorials, we try to do our best and comment the description and cells to give a thorough explanation of what is covered in the body of the tutorial. We will cover the script styles of tutorial here, as tutorials written as functions should be commented as functions.

Script Style Tutorials

Header

Required Headings in Header Comment

These headings and their content are intended to clarify the purpose of the tutorial, and how to modify and use it.

• Short Description - This is a one-line (<75 character) quick summary of the tutorial's general purpose
• Description - A detailed description of the tutorial, its intended uses, etc. Body text is indented 4 spaces from the comment marker for first-level.

Example header comment with the required headings:

%% t_conesMosaicAbsorptionNoise
% Illustrate noise generation for the coneMosaic object
%
% Description:
%    Illustrates the various ways to generate noise using the coneMosaic
%    object. We set coneMosaic.noiseFlag to 'random', 'frozen', and 'none'.
%
%    This tutorial also illustrates how to access some of the key fields of
%    the coneMosaic object programatically and make some plots of what is
%    in there.
%
%    It does not yet illustrate controlling the 'seed' for the 'frozen'
%    noise case.
%

Optional Headings in the Header Comment

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 tutorial 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.
• See Also - This section is for references to other MATLAB tutorials/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.
• 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 by a line of white space.

An example header comment including optional headings:

%% t_conesMosaicHexReg
% Create/use hex. mosaic w/ custom fixed cone spacing & inner segment diam.
%
% Description:
%    Generate and use a hexagonal mosaic with fixed (but custom) cone
%    spacing and inner segment diameter.
%
%    This shows how to generate a custom regular hexagonal mosaic, 
%    including a desired cone spacing and inner segment diameter. Here we
%    allow S-cones even at the foveola, and a 4-fold spacing between L/M
%    cones. Then show how to compute the isomerizations for this mosaic to
%    a simple stimulus.
%
% See Also:
%    t_coneMosaicHex
%

% History:
%    xx/xx/16  NPC  ISETBIO Team, Copyright 2016
%    08/08/17  NPC  Fixed and cleaned up for updated @coneMosaicHex class
%    07/23/18  JNM  Formatting

Function Style Tutorials

Tutorials written as functions will be commented and treated as functions, with few exceptions. To find documentation on how to comment functions, please see the Functions page, located here.

Header spacing requirements summary:

• 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
  • Description body text is 4 spaces offset from comment marker
• 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 3 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.