¿Cómo se documenta el código 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.

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

Answer 1

Me doy cuenta de que la pregunta es obsoleta, pero para el beneficio de Google: Matlab tiene una característica 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 2

documento mis oo código de la siguiente manera:

1. Al principio 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, I añadir una frase explicativa sobre él (en la misma línea)
3. Cada método está documentado como una función, es decir, tiene una línea de H1, una sinopsis, y una explicación de la entrada y parámetros de 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 H1- línea y el resto de la 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)), 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 quieres un buen documentación HTML, puede, además, utilizar m2html para generarlo para usted. M2html recogerá los textos de ayuda e incluso puede hacer gráficos de dependencia.

Editar 2 Mientras que m2html documenta muy bien 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 3

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

Answer 4

Trate Sphinx con la extensión matlabdomain. Sphinx es un paquete Python que documenta automáticamente el código usando ReStructuredText (rst) markup.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. Enviar errores y sugerencias al issue tracker on BitBucket.

Por ejemplo, el código siguiente 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 

se deberán documentar en un fichero primera como esto:

.. _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 this blog post.