Wie lassen sich Autoren- und Versionsinformationen in MATLAB-Funktionen integrieren?

Question

Diese Frage steht im Zusammenhang mit meiner vorherigen Frage: Formatierung der MATLAB m-Datei-Hilfe .

Was schreiben Sie normalerweise, um die Urheberschaft Ihrer eigenen Funktion zu beschreiben? Steht es am Ende des Funktionskörpers oder direkt nach dem Hilfetext vor dem Code?

Wie fügen Sie Versionsinformationen ein? Ist es möglich, die Version nach einer Funktionsänderung automatisch zu aktualisieren?

Dies ist das, was ich normalerweise einfüge:

% My Name <my@email>
% My company
% Created: September 2010
% Modified: October 2010

Bitte teilen Sie uns Ihre Gedanken und Ideen mit?

Answer 1

Ich habe eine Funktion im MATLAB Central File Exchange, das Sie dabei unterstützt, Ihre Funktion auf standardisierte Weise zu dokumentieren, und das mit Versionskontrollsoftware (CVS und Subversion; nicht Git) zusammenarbeitet, um das Autorenfeld und den Zeitpunkt der Änderung automatisch zu aktualisieren.

Sie geben einfach ein new an der Eingabeaufforderung, dann den Namen der Funktion, und der Rest wird sortiert.

Die grundlegende Vorlage für die Dokumentation, die ich verwende, lautet

function [outputArgs] = TestFunction(inputArgs)
%TESTFUNCTION Summary of this function goes here
% 
% [OUTPUTARGS] = TESTFUNCTION(INPUTARGS) Explain usage here
% 
% Examples: 
% 
% Provide sample usage code here
% 
% See also: List related files here

% $Author: rcotton $    $Date: 2010/10/01 18:23:52 $    $Revision: 0.1 $
% Copyright: Health and Safety Laboratory 2010

(Sie werden natürlich ein anderes Unternehmen in Ihrer Urheberrechtserklärung angeben wollen).

Die erste Zeile der Hilfedokumentation ist als H1-Zeile bekannt und wird von der Funktion lookfor und andere. Es ist wichtig, dass dies direkt nach der Funktionsdefinitionszeile kommt.

Wenn Sie verschiedene Anwendungsfälle haben (vielleicht mit und ohne optionale Argumente), dann sollten Sie jeden einzelnen beschreiben.

Le site Examples: y See also: Zeilen so formatiert sind, dass sie mit dem Hilfeberichtsgenerator funktionieren. (Ich habe gerade einen Fehler entdeckt - das Jahr sollte vor dem Firmennamen in der Copyright-Zeile stehen. Die Korrektur ist auf dem Weg.)

$Author: usw., sind für die Verwendung mit CSV/SVN formatiert. Da Git Hashes von Dateien verwendet, können Sie den Inhalt der Datei nicht ändern, ohne dass Git davon ausgeht, dass die Datei aktualisiert wurde.

Answer 2

Wir bewahren unseren Code in einem Subversion-Repository auf und verwenden die Schlüsselwort-Funktionalität, um diese Art von Informationen in die Header-Kommentare der m-Datei zu schreiben, wenn sie in das Repository übertragen wird. Wir setzen einen Block von Kommentaren direkt nach der ersten Funktionszeile in (die meisten) unserer m-Dateien.

Wenn Sie kein Quellcode-Kontrollsystem verwenden, dann:

1. Sie sollten wirklich sofort damit anfangen, eine zu benutzen.
2. Sie könnten ein Skript schreiben (in Matlab, warum nicht), um die benötigten Kommentarinformationen zu pflegen, und einen Prozess implementieren, der sicherstellt, dass Sie das Skript bei Bedarf ausführen.

Wir schreiben in der Regel keine Änderungsdaten oder Historien in unsere Quelldateien, das Repository verfolgt die Änderungen für uns. Das ist ein weiterer Grund, warum Sie ein Repository verwenden sollten.

Und während Sie über all das nachdenken, sollten Sie, falls Sie es noch nicht getan haben, Matlab's publish Funktionalität.

EDIT: @yuk: Ich vermute aufgrund Ihrer Erwähnung von TortoiseSVN, dass Sie unter Windows arbeiten. Es ist schon ein paar Jahre her, dass ich Subversion auf meinem Windows-PC installiert habe. Ich kann mich nicht erinnern, dass es bei der Installation irgendwelche Probleme gab, und ich bin nicht qualifiziert, Ihnen bei der Fehlersuche zu helfen - aber es gibt viele auf SO, die das können.

Um die Versionsinformationen (usw.) auf dem neuesten Stand zu halten, ist kein Skripting erforderlich. Sie fügen einfach die speziellen Zeichenketten ein, wie zum Beispiel $Rev$ , die Subversion als Schlüsselwörter an den Stellen in Ihren Dateien (wahrscheinlich in den Kommentaren), an denen Sie die Versionsinformationen (usw.) benötigen. Dies ist gut erklärt in der Subversion Buch .

Was die Matlab-Dokumentation anbelangt, so denke ich, dass die Veröffentlichungsfunktionen (und verwandte Funktionen) gut in der Desktop-Tools und Entwicklungsumgebung Handbuch, das online auf der Mathworks-Website verfügbar ist.

Answer 3

Als Hochleistungsvermerk weist darauf hin, dass eine Form der Quellcodekontrolle ideal ist, um diese Situation zu bewältigen. Wenn Sie jedoch Informationen von Hand hinzufügen, finden Sie hier ein paar Hinweise:

• Ich würde auf jeden Fall eine Zeile einfügen, in der die MATLAB-Version angegeben wird, in der Ihr Code geschrieben wurde, oder vielleicht auch, für welche Versionen Sie wissen, dass er funktioniert.

• Wenn Sie die Informationen hinzufügen, müssen Sie zwischen ihnen und dem Hilfe-Kommentarblock Platz lassen, wenn Sie nicht anzeigen möchten, wenn der Benutzer die Hilfe-Inhalte , etwa so:

  function myFunction
  %# Help text for function
  
  %# Your information

  Es sei denn, Sie tun mit der Hilfe angezeigt werden soll. Dann machen Sie einfach einen großen Kommentar-Block.