Update to documentation comments

Animate.m

@@ -1,7 +1,8 @@
 %ANIMATE Create an animation
 %
-% Help to create an animation which is a folder full of individual PNG
-% format frames numbered 0000.png, 0001.png and so on.
+% Helper class for creating animations.  Saves snapshots of a figture as a
+% folder of individual PNG format frames numbered 0000.png, 0001.png and so
+% on.
 %
 % Example::
 %
@@ -50,7 +51,8 @@
             % called NAME to hold the individual frames.
             %
             % Options::
-            % 'resolution',R    Set the resolution of the saved image in pixels per inch
+            % 'resolution',R    Set the resolution of the saved image to R pixels per
+            % inch.
 
             a.frame = 0;
             a.dir = name;

PGraph.m

@@ -1,15 +1,15 @@
 %PGraph Graph class
 %
-%   g = PGraph()        create a 2D, planar, undirected graph
-%   g = PGraph(n)       create an n-d, undirected graph
+%   g = PGraph()        create a 2D, planar embedded, directed graph
+%   g = PGraph(n)       create an n-d, embedded, directed graph
 %
 % Provides support for graphs that:
 %   - are directed
-%   - are embedded in coordinate system
+%   - are embedded in a coordinate system
 %   - have symmetric cost edges (A to B is same cost as B to A)
 %   - have no loops (edges from A to A)
-%   - have vertices are represented by integers vid
-%   - have edges are represented by integers, eid
+%   - have vertices that are represented by integers VID
+%   - have edges that are represented by integers EID
 %
 % Methods::
 %
@@ -63,6 +63,16 @@
 %   g.ne           number of edges
 %   g.nc           number of components
 %
+% Examples::
+%         g = PGraph();
+%         g.add_node([1 2]');  % add node 1
+%         g.add_node([3 4]');  % add node 1
+%         g.add_node([1 3]');  % add node 1
+%         g.add_edge(1, 2);    % add edge 1-2
+%         g.add_edge(2, 3);    % add edge 2-3
+%         g.add_edge(1, 3);    % add edge 1-3
+%         g.plot()
+%
 % Notes::
 % - Graph connectivity is maintained by a labeling algorithm and this
 %   is updated every time an edge is added.
@@ -131,7 +141,7 @@
         %                 'Euclidean' (default) or 'SE2'.
         %  'verbose'      Specify verbose operation
         %
-        % Note::
+        % Notes::
         % - Number of dimensions is not limited to 2 or 3.
         % - The distance metric 'SE2' is the sum of the squares of the difference 
         %   in position and angle modulo 2pi.
@@ -205,6 +215,10 @@ function clear(g)
         %
         % V = G.add_node(X, V2, C) as above but the added edge has cost C.
         %
+        % Notes::
+        % - Distance is computed according to the metric specified in the
+        %   constructor.
+        %
         % See also PGraph.add_edge, PGraph.data, PGraph.getdata.
 
             if length(coord) ~= g.ndims
@@ -232,7 +246,7 @@ function clear(g)
         %PGraph.setdata Set user data for node
         %
         % G.setdata(V, U) sets the user data of vertex V to U which can be of any 
-        % type such as number, struct, object or cell array.
+        % type such as a number, struct, object or cell array.
         %
         % See also PGraph.data.
 
@@ -243,7 +257,7 @@ function clear(g)
         %PGraph.data Get user data for node
         %
         % U = G.data(V) gets the user data of vertex V which can be of any 
-        % type such as number, struct, object or cell array.
+        % type such as a number, struct, object or cell array.
         %
         % See also PGraph.setdata.
             u = g.userdata{v};
@@ -257,9 +271,10 @@ function add_edge(g, v1, v2, d)
         % returns the edge id E.  The edge cost is the distance between the vertices.
         %
         % E = G.add_edge(V1, V2, C) as above but the edge cost is C.
-        % cost C.
         %
-        % Note::
+        % Notes::
+        % - Distance is computed according to the metric specified in the
+        %   constructor.
         % - Graph connectivity is maintained by a labeling algorithm and this
         %   is updated every time an edge is added.
         %
@@ -282,7 +297,8 @@ function add_edge(g, v1, v2, d)
         function c = component(g, v)
         %PGraph.component Graph component
         %
-        % C = G.component(V) is the id of the graph component 
+        % C = G.component(V) is the id of the graph component that contains vertex
+        % V.
             c = [];
             for vv=v
                 tf = ismember(g.labelset, g.labels(vv));
@@ -295,7 +311,7 @@ function add_edge(g, v1, v2, d)
         function e = edges(g, v)
         %PGraph.edges Find edges given vertex
         %
-        % E = G.edges(V) is a vector containing the id of all edges from vertex id V.
+        % E = G.edges(V) is a vector containing the id of all edges connected to vertex id V.
         %
         % See also PGraph.edgedir.
             e = [find(g.edgelist(1,:) == v) find(g.edgelist(2,:) == v)];
@@ -548,7 +564,7 @@ function goal(g, vg)
         % Notes::
         % - Combined with G.path performs a breadth-first search for paths to the goal.
         %
-        % See also PGraph.path, PGraph.Astar.
+        % See also PGraph.path, PGraph.Astar, Astar.
 
             % cost is total distance from goal
             g.goaldist = Inf*ones(1, numcols(g.vertexlist));
@@ -608,6 +624,10 @@ function goal(g, vg)
         % [D,W] = G.distances(P) as above but also returns W (1xN) with the 
         % corresponding vertex id.
         %
+        % Notes::
+        % - Distance is computed according to the metric specified in the
+        %   constructor.
+        %
         % See also PGraph.closest.
 
             d = g.distance_metric(p(:), g.vertexlist);
@@ -854,7 +874,7 @@ function highlight_path(g, path)
         %PGraph.highlight_path Highlight path
         %
         % G.highlight_path(P, OPTIONS) highlights the path defined by vector P
-        % which is a list of vertices comprising the path.
+        % which is a list of vertex ids comprising the path.
         %
         % Options::
         %  'NodeSize',S          Size of vertex circle (default 12)
@@ -1020,8 +1040,10 @@ function descend2(g, vg)
             g.labelset = union(g.labelset, l);
         end
 
-        % merge label1 and label2, lowest label dominates
         function merge(g, l1, l2)
+
+            % merge label1 and label2, lowest label dominates
+
             % get the dominant and submissive labels
             ldom = min(l1, l2);
             lsub = max(l1, l2);

Polygon.m

@@ -28,7 +28,7 @@
 %
 % Acknowledgement::
 %
-% The methods inside, intersection, difference, union, and xor are based on code
+% The methods: inside, intersection, difference, union, and xor are based on code
 % written by:
 %  Kirill K. Pankratov, kirill@plume.mit.edu,
 %  http://puddle.mit.edu/~glenn/kirill/saga.html
@@ -57,6 +57,7 @@
 % TODO
 %  split the code in two.  Simple polygon functions in Polgon class, subclass with
 %  Pankratov code to Polygon2.
+%  add method to detect empty polygon, overload isempty
 
 classdef Polygon < handle
 
@@ -165,11 +166,14 @@ function display(p)
         end
 
         function plot(plist, varargin)
-            %Polygon.plot Plot polygon
+            %Polygon.plot Draw polygon
             %
-            % P.plot() plot the polygon.
+            % P.plot() draws the polygon P in the current plot.
             %
             % P.plot(LS) as above but pass the arguments LS to plot.
+            %
+            % Notes::
+            % - The polygon is added to the current plot.
 
             opt.fill = [];
             [opt,args] = tb_optparse(opt, varargin);
@@ -222,6 +226,8 @@ function plot(plist, varargin)
             %Polygon.area Area of polygon
             %
             % A = P.area() is the area of the polygon.
+            %
+            % See also Polygon.moments.
             a = p.moments(0, 0);
         end
 
@@ -230,15 +236,15 @@ function plot(plist, varargin)
             %
             % A = P.moments(p, q) is the pq'th moment of the polygon.
             %
-            % See also mpq_poly.
+            % See also Polygon.area, Polygon.centroid, mpq_poly.
             m = mpq_poly(p.vertices, mp, mq);
         end
 
         function q = transform(p, T)
-            %Polygon.transform Transformation of polygon vertices
+            %Polygon.transform Transform polygon vertices
             %
             % P2 = P.transform(T) is a new Polygon object whose vertices have
-            % been transfored by the 3x3 homgoeneous transformation T.
+            % been transformed by the SE(2) homgoeneous transformation T (3x3).
             if length(T) == 3
                 T = se2(T);
             end
@@ -248,16 +254,18 @@ function plot(plist, varargin)
         function f = inside(p, points)
             %Polygon.inside Test if points are inside polygon
             %
-            % IN = P.inside(P) tests if points given by columns of P are
-            % inside the polygon.  The corresponding elements of IN are
-            % either true or false.
+            % IN = P.inside(P) tests if points given by columns of P (2xN) are inside
+            % the polygon.  The corresponding elements of IN (1xN) are either true or
+            % false.
             IN = inpolygon(points(1,:), points(2,:), p.x, p.y)
         end
 
         function c = centroid(p)
             %Polygon.centroid Centroid of polygon
             %
             % X = P.centroid() is the centroid of the polygon.
+            %
+            % See also Polygon.moments.
             xc = p.moments(1,1) / p.area();
         end
 
@@ -289,9 +297,9 @@ function plot(plist, varargin)
         function f = intersect_line(p, l)
             %Polygon.intersect_line Intersection of polygon and line segment
             %
-            % I = P.intersect_line(L) is the intersection points of a polygon P
-            % with the line segment L=[x1 x2; y1 y2].  I is an Nx2 matrix with
-            % one column per intersection, each column is [x y]'.
+            % I = P.intersect_line(L) is the intersection points of a polygon P with
+            % the line segment L=[x1 x2; y1 y2].  I (2xN) has one column per
+            % intersection, each column is [x y]'.
 
             f = [];
             % find intersections
@@ -384,7 +392,7 @@ function plot(plist, varargin)
         function r = union(p, q)
             %Polygon.union Union of polygons
             %
-            % I = P.union(Q) is a Polygon representing the
+            % I = P.union(Q) is a polygon representing the
             % union of polygons P and Q.
             %
             % Notes::
@@ -428,8 +436,8 @@ function plot(plist, varargin)
         function r = xor(p, q)
             %Polygon.xor Exclusive or of polygons
             %
-            % I = P.union(Q) is a Polygon representing the
-            % union of polygons P and Q.
+            % I = P.union(Q) is a polygon representing the
+            % exclusive-or of polygons P and Q.
             %
             % Notes::
             % - If these polygons are not intersecting, returns a polygon with
@@ -1296,6 +1304,7 @@ function plot(plist, varargin)
 end
 
 function [x1,y1,x2,y2] = linechk(x1,y1,x2,y2)
+
     % LINECHK Input checking for line segments.
 
     %  Copyright (c) 1995 by Kirill K. Pankratov

about.m

@@ -5,6 +5,15 @@
 %
 % ABOUT X  as above but this is the command rather than functional form
 %
+% Examples::
+%         >> a=1;
+%         >> about a
+%         a [double] : 1x1 (8 bytes)
+%
+%         >> a = rand(5,7);
+%         >> about a
+%         a [double] : 5x7 (280 bytes)
+%
 % See also WHOS.
 
 % Copyright (C) 1993-2014, by Peter I. Corke

angdiff.m

@@ -7,7 +7,6 @@
 %
 % D = ANGDIFF(TH) returns the equivalent angle to TH in the interval [-pi pi).
 %
-% Return the equivalent angle in the interval [-pi pi).
 
 % Copyright (C) 1993-2014, by Peter I. Corke
 %

bresenham.m

@@ -1,11 +1,13 @@
 %BRESENHAM Generate a line
 %
-% P = BRESENHAM(X1, Y1, X2, Y2) is a list of integer coordinates for 
-% points lying on the line segement (X1,Y1) to (X2,Y2).  Endpoints 
-% must be integer.
+% P = BRESENHAM(X1, Y1, X2, Y2) is a list of integer coordinates (2xN) for 
+% points lying on the line segement (X1,Y1) to (X2,Y2).
 %
 % P = BRESENHAM(P1, P2) as above but P1=[X1,Y1] and P2=[X2,Y2].
 %
+% Notes::
+% - Endpoints must be integer values.
+%
 % See also ICANVAS.
 
 

ccodefunctionstring.m

@@ -34,7 +34,8 @@
 %          myrot = rotz(q3)*roty(q2)*rotx(q1)
 %
 %          % Generate C-function string
-%          [funstr, hdrstr] = ccodefunctionstring(myrot,'output','foo','vars',{Q},'funname','rotate_xyz')
+%          [funstr, hdrstr] = ccodefunctionstring(myrot,'output','foo', ...
+%          'vars',{Q},'funname','rotate_xyz')
 %
 % Notes::
 % - The function wraps around the built-in Matlab function 'ccode'. It does

circle.m

@@ -1,10 +1,11 @@
 %CIRCLE Compute points on a circle
 %
-% CIRCLE(C, R, OPT) plot a circle centred at C with radius R.
+% CIRCLE(C, R, OPT) plots a circle centred at C (1x2) with radius R on the current
+% axes.
 %
-% X = CIRCLE(C, R, OPT) return an Nx2 matrix whose rows define the 
+% X = CIRCLE(C, R, OPT) is a matrix (2xN) whose columns define the 
 % coordinates [x,y] of points around the circumferance of a circle 
-% centred at C and of radius R.
+% centred at C (1x2) and of radius R.
 %
 % C is normally 2x1 but if 3x1 then the circle is embedded in 3D, and X is Nx3,
 % but the circle is always in the xy-plane with a z-coordinate of C(3).

colnorm.m

@@ -1,7 +1,7 @@
 %COLNORM Column-wise norm of a matrix
 %
-% CN = COLNORM(A) is an Mx1 vector of the normals of each column of the
-% matrix A which is NxM.
+% CN = COLNORM(A) is  vector (1xM) of the normals of each column of the
+% matrix A (NxM).
 
 % Copyright (C) 1993-2014, by Peter I. Corke
 %

diff2.m

@@ -1,7 +1,14 @@
-%DIFF2 Two point difference
+%DIFF2 First-order difference
 %
-% D = DIFF2(V) is the 2-point difference for each point in the vector v
-% and the first element is zero.  The vector D has the same length as V.
+% D = DIFF2(V) is the first-order difference (1xN) of the series data in 
+% vector V (1xN) and the first element is zero.
+%
+% D = DIFF2(A) is the first-order difference (MxN) of the series data in 
+% each row of the matrix A (MxN) and the first element in each row is zero.
+%
+% Notes::
+% - Unlike the builtin function DIFF, the result of DIFF2 has the same
+%   number of columns as the input.
 %
 % See also DIFF.