Commenting style example

From OPS
Jump to: navigation, search

All CReSIS Toolbox Development Guides

Contents

Overview

Please follow the syntax of the function headers exactly. Also, make use of the "cell" feature within the editor (cells are created by using two percentage signs in a row).


Function Comments

These are the comments that should be at the top of each function.

General format:

  1. Print function and input/output arguments
  2. Description of function
  3. List of input arguments
  4. List of output arguments
  5. Authors that contributed
  6. List of functions that might be of interest to someone looking at this function
function link_figures(fig_list,param)
% link_figures(fig_list,param)
%
% Simple function to link axes more quickly.
%
% fig_list: list of figure handles or numbers, default is all figures
%
% param: parameter to pass to linkaxes second argument, default is 'xy'
%
% Author: First Last
%
% See also: 
function gps = read_gps_cresis(fn,param)
% gps = read_gps_cresis(fn,param)
%
% This function reads the DGPS/INS data output from the Waypoint Inertial
% Explorer from NovAtel, Canada. The format is:
%  16 header lines
%  9 columns (space in between each one)
%  1: 10 chars: GPS Date YYYY/MM/DD
%  2: 9 chars: GPS Time Seconds of Day S.FF (sec)
%  3: 14 chars: Latitude (deg)
%  4: 15 chars: Longitude (deg)
%  5: 12 chars: H-ellipsoid WGS1984 (m)
%  6: 14 chars: Roll (deg)
%  7: 14 chars: Pitch (deg)
%  8: 14 chars: Heading (deg)
%  9: 12 chars: Standard devision of position, estimate of accuracy (m)
% Example:
%2013/09/21 72007.52  51.1173063345 -114.0195467099     1067.619  -1.1887370000  11.5422700000 212.3486410000        0.028
%
% fn: string containing input filename to read in
%
% param: structure containing fields to control how file is read in
%
%  .time_reference: string containing 'gps' or 'utc' which indicates the time
%  reference used in the file (i.e. GPS time or UTC time which are separated
%  by leap seconds).
%
% gps: structure of the output
%  .lat: Latitude in degrees, zero at equator, increasing toward north
%  .lon: Longitude in degrees, zero at prime meridian, increasing toward east
%  .elev
%  .roll
%  .pitch
%  .heading
%
% Examples:
%  fn = 'C:\Users\dangermo\Desktop\GPS\test1.txt';
%  gps = read_gps_cresis(fn);
%  plot_gps(gps);
%
% Author: First Last, First Last, ...
%
% See also: read_gps_applanix, read_gps_atm, read_gps_csv, read_gps_litton,
%   read_gps_nmea, read_gps_novatel, read_gps_reveal, read_gps_traj,
%   read_gps_txt, plot_gps

Editor Cell Comments

%% First cell title
% ====================================================================
% Additional detailed comments

%% First: Sub first cell first subcell

%% First: Sub first cell second subcell

CODE HERE

%% Second cell title
% ====================================================================

CODE HERE

%% Third cell title
% ====================================================================

CODE HERE

Class Object Comments

Place an editor cell before each function, followed by a regular comment.

    %% set_name
    function obj = set_name(obj, surface_old_name, surface_new_name)
      % obj.set_name(surface_old_name, surface_new_name)
      %
      % Input: 
      %   surface_old_name: A string that matches the name of 
      %   the surface in the surf struct array in the object.
      %   surface_new_name: A string that you want to replace the
      %   surface_old_name.
      %
      % Return: 
      %   1. surface_old_name changed to surface_new_name, if 
      %   surface_old_name is found.
      %   2. Throws an error if surface_old_name is not found.
      %
      % See also: set_name
      
      if ~(isa(surface_old_name, 'char') && isa(surface_new_name, 'char'))
        error('Both input must have type char.');
      else
        match_idx = obj.get_index(surface_old_name);            
        obj.surf(match_idx).name = surface_new_name;
      end
    end
Personal tools
Namespaces

Variants
Actions
Navigation
Tools