Comment documenter le code MATLAB orienté objet ?

Question

Je suis en train d'écrire une application importante à l'aide de MATLAB orienté objet, et cela m'a fait réfléchir à la façon de documenter le code. S'il s'agissait de C, j'utiliserais Doxygen. Pour Java, j'utiliserais JavaDoc. Les deux ont des normes largement acceptées sur la façon dont la documentation des classes et des méthodes doit se présenter et ce qu'elle doit contenir.

Mais qu'en est-il du code MATLAB ? Le plus que j'ai vu dans les propres cours de TMW est une courte phrase ou deux au début du cours, et je ne peux pas trouver de sujets consacrés à la documentation d'applications MATLAB importantes.

Alors, comment documenter vos cours de MATLAB ? Des problèmes de style particuliers ou des outils supplémentaires ?

Answer 1

Je réalise que la question est périmée, mais pour le bénéfice de Google : Matlab a une fonction intégrée pour cela. Vous écrivez vos commentaires dans un certain style (à la JavaDoc) et ils sont repris par les fonctions help et doc. Cette fonction peut être utilisée pour documenter les classes, les propriétés et les méthodes. C'est étonnamment complet, mais un peu délicat. La doc est ici :

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

Answer 2

Je documente mon code oo de la manière suivante :

1. Au début du fichier qui contient 'classdef', j'écris un résumé de ce que fait la classe, et de son utilisation typique. J'explique également les propriétés en détail et j'ajoute une description d'une phrase pour chaque méthode.
2. Après chaque définition de propriété, j'ajoute une phrase explicative à son sujet (sur la même ligne)
3. Chaque méthode est documentée comme une fonction, c'est-à-dire qu'elle possède une ligne H1, un synopsis et une explication des paramètres d'entrée et de sortie.

Lorsque vous appelez 'doc myClass', vous verrez (1) au début, suivi de la liste des propriétés expliquées par les phrases que vous avez ajoutées en (2) et de la liste des méthodes qui affichent la ligne H1 et le reste de l'aide (3) si vous cliquez sur le lien.

De plus, toutes mes classes sous-classent une superclasse générale qui implémente (entre autres) la méthode 'help' qui appelle doc(class(obj)), ce qui me permet de faire apparaître l'aide à partir de chaque instance de la classe.

Exemple

%# 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

Edit 1 Si vous voulez une belle documentation html, vous pouvez, en plus, utiliser m2html pour le générer pour vous. M2html rassemblera les textes d'aide et peut même faire des graphiques de dépendance.

Edit 2 Bien que m2html documente agréablement le code Matlab standard, il ne dispose d'aucun support spécifique pour les classes. Cela signifie que vous obtenez les méthodes sous forme de "sous-fonctions" liées à la classe, mais vous n'obtenez pas un résumé aussi agréable que celui que vous obtiendriez avec Doxygen, ou que celui que vous obtenez avec le navigateur de documentation intégré.

Answer 3

Essayez Sphinx avec le matlabdomain extension. Sphinx est un Python qui documente automatiquement le code en utilisant Balises ReStructuredText (rst) . L'extension sphinxcontrib-matlabdomain permet l'auto-documentation du code MATLAB qui utilise le premier balisage reconnu par Sphinx dans ses docstrings. Envoyez les bogues et les suggestions à l'adresse suivi des problèmes sur BitBucket .

Par exemple, le code suivant dans 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

serait documenté dans un fichier rst comme ceci :

.. _my-project

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

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

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

et produirait du html (ou pdf, latex, et beaucoup d'autres) comme ce qui est montré sur cet article de blog .

Answer 4

Il existe un adaptateur Doxygen pour M-Files sur FileExchange. http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab .