Guía de estilo para MATLAB: Documentación

La usabilidad de un programa depende de su documentación. Si el programa está bien documentado, será posible usarlo fácilmente. De lo contrario, el programa será inútil. Aquí propongo el contenido mínimo en el texto de ayuda de funciones escritas en MATLAB.

Supongamos que creamos una función para sumar dos números

function y = add(a,b)
switch nargin
    case 2
        c = a + b;
    case 1
        c = a + a;
    otherwise
        c = NaN;
end

Se deberán incluir al menos las siguientes secciones en el texto de ayuda:

Contenido

• Cabecera
• Descripción
• Autores
• Referencias
• Sintaxis
• Entrada
• Salida
• Ejemplos
• See also

Cabecera

La primer línea del texto de ayuda (llamada H1) inicia con el nombre de la función y una breve descripción de la función. Esta línea es importante porque lookfor busca en ella una palabra clave dada. Además, Contents despliegan esta línea para cada archivo .m en el directorio de trabajo.

% ADD  Suma dos números.
%

Descripción

En esta sección se presenta una descripción detallada de la función en el contexto del problema general o el área temática a la que pertenece. Se puede plantear el problema que la función atiende, describir las variables ambientales, proporcionar antecedentes, explicar la metodología y análisis matemáticos usados.

% Descripción:
%     Suma dos números usando la suma de los números reales. Esta suma,
%     junto con los números reales, cumplen con los cuatro axiomas de
%     grupo: cerradura, asociatividad, existencia de elemento neutro y
%     existencia de elementos inversos. Además, la suma es conmutativa, por
%     lo que los reales con esta suma son un grupo abeliano.
%

Autores

Admás del nombre de los autores, es importante incluir algún medio de contacto, por ejemplo, dirección de correo electrónico.

% Autor:
%     Evaristo Rojas <evaristo.rojas@islas.org.mx>
%

Referencias

Debemos incluir las referencias en las que se encuentran los antecedentes de nuestra descripción y las referencias en las que basamos los métodos y análisis matemáticos. También podemos usar esta sección para referir al lector a las definiciones de los términos usados.

% Referencias:
%     - <a href="http://es.wikipedia.org/wiki/Grupo_abeliano">Grupo abeliano</a>
%     - <a href="http://es.wikipedia.org/wiki/Suma">Suma</a>
%

Sintaxis

Enlistamos todas las posibles maneras en las que se puede invocar la función.

% Sintaxis:
%     Y = add(A) suma A a sí mismo.
%     Y = add(A,B) suma A mas B.
%

Entrada

Enlistamos todos los posibles argumentos de entrada de la función, los cuales se mostraron en la sección de Sintaxis. Indicamos su clase y dominio. Debe quedar claro cual es la relación entre estos parámetros y las variables del problema general.

% Entrada:
%     A  (double)  Número real que será sumado.
%     B  (double)  Número real que será sumado.
%

Salida

Enlistamos todos los valores de salida de la función, los cuales se mostraron en la sección de Sintaxis. Indicamos su clase y dominio.

% Salida:
%     Y  (double)  Total de la suma.
%

Ejemplos

Incluiremos ejeplos que sean autónomos, es decir, que se puedan copiar y pegar en la ventana de comandos para ser ejecutados. Se deberá incluir un ejemplo por cada manera mostrada en la sección de Sintaxis.

% Ejemplos:
%     Y = add(1); % devuelve Y = 2
%     Y = add(2,3); % devuelve Y = 5
%     Y = add(); % devuelve Y = NaN
%

See also

Al incluir nombres de funciones al final del texto de ayuda en una línea que inicie con % See also se crearán enlaces hacia dichas funciones.

% See also:
%     sum, cumsum, diff.
%

Resultado

Escribiendo el texto de ayuda de esta manera, obtendremos ayuda completa que nos permitirar usar la función fácilmente.

help add

  ADD  Suma dos números.
  Descripción:
      Suma dos números usando la suma de los números reales. Esta suma,
      junto con los números reales, cumplen con los cuatro axiomas de
      grupo: cerradura, asociatividad, existencia de elemento neutro y
      existencia de elementos inversos. Además, la suma es conmutativa, por
      lo que los reales con esta suma son un grupo abeliano.
  Autor:
      Evaristo Rojas <evaristo.rojas@islas.org.mx>
  Referencias:
      - Grupo abeliano
      - Suma
  Sintaxis:
      Y = add(A) suma A a sí mismo.
      Y = add(A,B) suma A mas B.
  Entrada:
      A  (double)  Número real que será sumado.
      B  (double)  Número real que será sumado.
  Salida:
      Y  (double)  Total de la suma.
  Ejemplos:
      Y = add(1); % devuelve Y = 2
      Y = add(2,3); % devuelve Y = 5
      Y = add(1,2,3); % devuelve Y = NaN 
  See also:
      sum, cumsum, diff.

Referencias

• MATLAB Programming Style Guide
• Add Help for Your Program

Código fuente de esta entrada