Как включить информацию об авторстве и версии в функции MATLAB [закрыто]

Этот вопрос связан с моим предыдущим: MATLAB M-file help formatting.

Что вы обычно пишете, чтобы описать авторство вашей собственной функции? Помещаете ли вы его в конце тела функции или сразу после текста справки перед любым кодом?

Как вы включаете информацию о версии? Возможно ли автоматическое обновление версии после модификации функции?

Это то, что я обычно включаю: 

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

Пожалуйста, поделитесь своими мыслями, идеями?

3 4
matlab function documentation

3 ответа:

У меня есть функция в MATLAB Central File Exchange, которая помогает вам документировать вашу функцию стандартным способом и работает с программным обеспечением контроля версий (CVS и Subversion; не git) для автоматического обновления поля автора и времени модификации.

Вы просто вводите new в командной строке, затем имя функции, и она сортирует остальное.

Основным шаблоном для документации, который я использую, является 

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

(Вы, очевидно, захотите другого компания в вашем заявлении об авторских правах.)

Первая строка справочной документации известна как строка H1 и используется функцией lookfor, среди прочих. Важно, что это происходит сразу после строки определения функции.

Если у вас есть разные варианты использования (возможно, с дополнительными аргументами и без них), то вы должны описать каждый из них.

Строки Examples: и See also: отформатированы так, как это работает с генератором отчетов help. (Я только что заметил ошибку - год должен быть перед названием компании в строке авторского права. Починка на своем пути.)

$Author:, и т.д., форматируются для использования с CSV / SVN. Поскольку git использует хэши файлов,вы не можете изменить содержимое файла, не думая, что он был обновлен.

6

Мы храним наш код в репозитории Subversion и используем функциональность keywords для записи такого рода информации в комментарии заголовка m-файла, когда он фиксируется в репозитории. Мы помещаем блок комментариев сразу после начальной строки функции в (большинство) наших m-файлов.

Если вы не используете систему управления исходным кодом, то:

  1. вы действительно должны начать использовать его прямо сейчас.
  2. Вы можете написать сценарий (в Matlab, почему бы и нет) для поддержания комментируйте информацию, которая вам необходима, и реализуйте некоторый процесс, чтобы гарантировать, что вы запустите сценарий, когда это необходимо.

Мы обычно не помещаем даты изменений или истории в наши исходные файлы, репозиторий отслеживает изменения для нас. Это еще одна причина, по которой вы должны использовать его.

И, пока вы думаете обо всем этом, если вы еще не сделали этого: проверьте функциональность Matlab publish.

EDIT: @yuk: я догадываюсь по вашему упоминанию TortoiseSVN, что вы работа над окнами. Прошло уже несколько лет с тех пор, как я установил Subversion на свой компьютер с Windows. Я не помню никаких проблем с установкой, и я не квалифицирован, чтобы помочь вам отладить вашу-но есть много на SO, которые есть.

Что касается обновления информации о версии (etc), то здесь не требуется никаких сценариев. Вы просто включаете специальные строки, такие как $Rev$, которые Subversion распознает как ключевые слова в местах в ваших файлах (вероятно, в комментариях), где вы требуется информация о версии (и т. д.). Это хорошо объяснено в книгеSubversion .

Что касается документации Matlab, я думаю, что функции публикации (и связанные с ними) хорошо объяснены в руководстве Desktop Tools and Development Environment, которое доступно в интернете на веб-сайте Mathworks.
3

Как указывает High Performance Mark, некоторая форма управления исходным кодом идеально подходит для обработки этой ситуации. Однако, если вы добавляете информацию вручную, вот несколько указателей:

  • Я бы обязательно включил строку, указывающую версию MATLAB, в которой был написан ваш код, или, возможно, какие версии вы знаете, для которых он работает.

  • Добавляя информацию, вы должны оставить пространство между ней и блоком комментариев справки, если вы не хотите чтобы отобразить его, когда пользователь просматривает содержимое справки , например: 

    function myFunction
%# Help text for function

%# Your information

    Если только вы не хотите, чтобы он отображался с помощью. Тогда просто сделайте один большой блок комментариев.

1