steps - matlab instructions

¿Cómo documentar el código de MATLAB orientado a objetos?

Question

Estoy escribiendo una aplicación considerable utilizando MATLAB orientado a objetos, y esto me ha hecho pensar en cómo documentar el código. Si esto fuera C, usaría Doxygen. Para Java, usaría JavaDoc. Ambos tienen estándares acordados en su mayoría sobre cómo debería verse la documentación de clases y métodos y qué debería contener.

Pero, ¿qué pasa con el código de MATLAB? Lo máximo que he visto en las propias clases de TMW es una o dos oraciones cortas en la parte superior de la clase, y no encuentro ningún tema dedicado a la documentación de aplicaciones considerables de MATLAB.

Entonces, ¿cómo documenta sus clases de MATLAB? ¿Algún problema de estilo en particular o herramientas adicionales?

Answer 1

Documenta mi código de oo de la siguiente manera:

1. Al comienzo del archivo que contiene ''classdef'', escribo un resumen de lo que hace la clase y el uso típico. También explico las propiedades en detalle y agrego una descripción de 1 oración de cada método.
2. Después de cada definición de propiedad, agrego una oración explicativa al respecto (en la misma línea)
3. Cada método está documentado como una función, es decir, tiene una línea H1, una sinopsis y una explicación de los parámetros de entrada y salida.

Cuando llame a ''doc myClass'', verá (1) al principio, seguido de la lista de propiedades explicadas por las oraciones que agregó en (2) y la lista de métodos que muestran la línea H1 y el resto del ayuda (3) si hace clic en el enlace.

Además, todas mis clases subclasifican una superclase general que implementa (entre otros) el método ''help'' que llama a doc (class (obj)), lo que me permite mostrar la ayuda de cada instancia de la clase.

Ejemplo

%# MYCLASS is a sample class
%# All this text will show up at the top of the help if you call ''doc myClassName''
%#
%# myClass is an example for documentation. It implements the following properties and methods:
%# PROPERTIES
%#    myProp - empty sample property (some more explanation could follow here)
%#
%# METHODS
%#    myMethod - sample method that calls doc
%#

classdef myClass

properties
    myProp = []; %# empty sample property
end %# properties

methods

%%# MYMETHOD -- use %% so that you can easily navigate your class file
function myMethod(obj)
%#MYMETHOD calls up the help for the object
%#
%# SYNOPSIS myMethod(obj)
%# INPUT obj: the object
%# OUTPUT none
%#
   try
      doc(class(obj))
   catch
      help(class(obj))
   end
   end %#myMethod
end %#methods

end %#myClass

Editar 1 Si desea una buena documentación html, puede, además, usar m2html para generarla. M2html recogerá los textos de ayuda e incluso puede hacer gráficos de dependencia.

Editar 2 Mientras m2html documenta el código Matlab estándar, no tiene soporte específico para las clases. Esto significa que tiene los métodos como ''subfunciones'' vinculados en la clase, pero no obtiene un resumen tan bueno como el que obtendría con Doxygen, o que obtiene con el navegador de documentación integrado.

Answer 2

Existe un adaptador Doxygen para M-Files en FileExchange, consulte http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab .

Answer 3

Me doy cuenta de que la pregunta es obsoleta, pero para el beneficio de Google: Matlab tiene una función incorporada para eso. Usted escribe sus comentarios en un cierto estilo (a la JavaDoc) y los recogen las funciones de ayuda y documentación. Se puede usar para documentar clases, propiedades y métodos. Es sorprendentemente completo, pero un poco meticuloso. El documento está aquí:

http://www.mathworks.com/help/matlab/creating-help.html

Answer 4

Pruebe Sphinx con la extensión matlabdomain . Sphinx es un paquete de Python que documenta automáticamente el código utilizando el marcado ReStructuredText (rst) . La extensión sphinxcontrib-matlabdomain permite la auto-documentación del código MATLAB que usa el primer marcado reconocido por Sphinx en sus documentos. Envía errores y sugerencias al rastreador de problemas en BitBucket .

Por ejemplo, el siguiente código en my_project/my_fun.m :

function [outputs] = my_fun(args)
% MY_FUN does really cool stuff
% [OUTPUTS] = MY_FUN(ARGS)
%
% :param args: Input arguments
% :type args: cell array
% :returns: outputs
% :raises: :exc:`my_project.InvalidInput`

code ...
end

estaría documentado en un primer archivo como este:

.. _my-project

My Project
==========
.. automodule:: my_project

    This folder contains all the functions and classes for my project.

My Function
-----------
.. autofunction:: my_fun

y produciría html (o pdf, látex y muchos otros) como lo que se muestra en esta publicación de blog .