Wie dokumentiert man objektorientierten MATLAB-Code?

Question

Ich schreibe eine umfangreiche Anwendung mit objektorientierten MATLAB, und das hat mich darüber nachdenken, wie man den Code dokumentiert. Wenn das C wäre, würde ich Doxygen benutzen. Für Java würde ich JavaDoc verwenden. Beide haben meist vereinbarte Standards für die Art und Weise, wie Klassen- und Methodendokumentation aussehen sollte und was sie enthalten sollte.

Aber was ist mit MATLAB-Code? Die meisten, die ich in TMWs eigenen Klassen gesehen habe, sind ein oder zwei kurze Sätze an der Spitze der Klasse, und ich finde keine Themen, die der Dokumentation umfangreicher MATLAB-Anwendungen gewidmet sind.

Wie dokumentieren Sie Ihre MATLAB-Klassen? Irgendwelche besonderen Stilprobleme oder zusätzliche Werkzeuge?

Answer 1

Ich weiß, die Frage ist abgestanden, aber für Google: Matlab hat eine eingebaute Funktion dafür. Sie schreiben Ihre Kommentare in einem bestimmten Stil (a la JavaDoc) und sie werden von den Hilfe- und Dokumentfunktionen abgeholt. Es kann verwendet werden, um Klassen, Eigenschaften und Methoden zu dokumentieren. Es ist überraschend komplett und doch ein bisschen knifflig. Der Doc ist hier:

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

Answer 2

ich meine oo Code dokumentieren die folgende Art und Weise:

1. Zu Beginn der Datei, die ‚classdef‘ enthält, schreibe ich eine Zusammenfassung dessen, was die Klasse der Fall ist, und typische Nutzung. Ich erkläre Eigenschaften auch im Detail und füge eine 1-Satz-Beschreibung jeder Methode hinzu.
2. Nach jeder Eigenschaftsdefinition füge ich einen erklärenden Satz darüber hinzu (in der gleichen Zeile)
3. Jede Methode wird wie eine Funktion dokumentiert, dh es hat eine H1-Zeile, eine Synopse und eine Erklärung der Eingabe und Ausgabeparameter.

Wenn Sie ‚doc myClass‘ nennen, werden Sie (1) am Anfang sehen, gefolgt von der Liste der Eigenschaften von den Sätzen erklärt man in (2) und die Liste der Methoden, die die H1- zeigen hinzugefügt Linie und der Rest der Hilfe (3), wenn Sie auf den Link klicken.

Außerdem bilden alle meine Klassen eine allgemeine Oberklasse, die (unter anderem) die Methode 'help' implementiert, die doc (class (obj) aufruft), wodurch ich die Hilfe von jeder Instanz der Klasse aufrufen kann.

Beispiel

%# 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 Wenn Sie eine schöne HTML-Dokumentation möchten, können Sie darüber hinaus verwenden m2html es für Sie zu generieren. M2html sammelt die Hilfetexte und kann sogar Abhängigkeitsgraphen erstellen.

Edit 2 Während m2html Standard-Matlab-Code schön dokumentiert, hat es keine spezifische Unterstützung für Klassen. Das bedeutet, dass Sie die Methoden als "Unterfunktionen" in der Klasse verknüpfen, aber Sie erhalten keine so gute Zusammenfassung, wie Sie mit Doxygen erhalten oder die Sie mit dem integrierten Dokumentationsbrowser erhalten.

Answer 3

Es existiert ein Doxygen-Adapter für M-Files auf FileExchange, siehe http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab.

Answer 4

Versuchen Sphinx mit der matlabdomain Erweiterung. Sphinx ist ein Python Paket, das den Code unter Verwendung von ReStructuredText (rst) markup automatisch dokumentiert.Die Erweiterung sphinxcontrib-matlabdomain ermöglicht die automatische Dokumentation von MATLAB-Code, der das erste von Sphinx in seinen Docstrings erkannte Markup verwendet. Senden Sie Fehler und Vorschläge an die issue tracker on BitBucket.

Zum Beispiel der folgende Code in 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 

würde in einer ersten Datei wie folgt zu dokumentieren:

.. _my-project 

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

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

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

und würde HTML (oder pdf, Latex, und viele andere produzieren) wie das, was auf this blog post angezeigt wird.