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
Secciones del texto de ayuda
Se deberán incluir al menos las siguientes secciones en el texto de ayuda:
- 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, automáticamente se crearán enlaces hacia dichas funciones.
% See also: % sum, cumsum, diff. %
Ejemplo
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