web-dev-qa-db-ja.com

オブジェクト指向のMATLABコードを文書化する方法は？

私はオブジェクト指向のMATLABを使用してかなり大きなアプリケーションを書いていますが、これにより、コードを文書化する方法について考えるようになりました。これがCの場合、Doxygenを使用します。 Javaの場合、JavaDocを使用します。どちらも、クラスとメソッドのドキュメントの外観とその内容について、ほぼ合意された標準を持っています。

しかし、MATLABコードはどうですか？ TMW自身のクラスで私が見た中で最も多いのは、クラスの先頭にある1つか2つの短い文であり、大規模なMATLABアプリケーションの文書化に関するトピックは見つかりません。

では、MATLABクラスをどのように文書化しますか？特定のスタイルの問題や追加のツールはありますか？

matlabdocumentation
33
jjkparker

質問は古くなっていると思いますが、Googleの利益のために：Matlabにはそのための組み込み機能があります。コメントを特定のスタイル（JavaDoc）で作成すると、ヘルプ関数とdoc関数によってコメントが取得されます。クラス、プロパティ、およびメソッドを文書化するために使用できます。それは驚くほど完全ですが、少し気難しいです。ドキュメントはここにあります：

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

27
Patrick Mineault

私は自分のooコードを次の方法で文書化します。

  1. 'classdef'を含むファイルの先頭に、クラスの機能と一般的な使用法の概要を記述します。また、プロパティについて詳しく説明し、各メソッドの1文の説明を追加します。
  2. 各プロパティ定義の後に、それについての説明文を1つ追加します（同じ行に）
  3. 各メソッドは関数のように文書化されています。つまり、H1行、概要、および入力パラメーターと出力パラメーターの説明があります。

'doc myClass'を呼び出すと、最初に（1）が表示され、続いて（2）で追加した文で説明されているプロパティのリストと、H1行と残りの部分を表示するメソッドのリストが表示されます。リンクをクリックするとヘルプ（3）が表示されます。

さらに、すべてのクラスは、doc（class（obj））を呼び出すメソッド 'help'を（とりわけ）実装する一般的なスーパークラスをサブクラス化します。これにより、クラスのすべてのインスタンスからヘルプを表示できます。

例

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

編集1素敵なhtmlドキュメントが必要な場合は、さらに m2html を使用して生成できます。 M2htmlはヘルプテキストを収集し、依存関係グラフを作成することもできます。

編集2m2htmlは標準のMatlabコードを適切に文書化しますが、クラスに対する特定のサポートはありません。これは、クラスでリンクされた「サブ関数」としてメソッドを取得することを意味しますが、Doxygenで取得する、または組み込みのドキュメントブラウザで取得するほど素晴らしい要約は取得しません。

10
Jonas

matlabdomain 拡張子を付けて Sphinx を試してください。 Sphinxは Python パッケージであり、 ReStructuredText（rst）マークアップ を使用してコードを自動ドキュメント化します。拡張機能sphinxcontrib-matlabdomainを使用すると、ドキュメント文字列でSphinxによって認識された最初のマークアップを使用するMATLABコードの自動ドキュメント化が可能になります。バグや提案を BitBucketの課題追跡システム に送信します。

たとえば、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

このような最初のファイルに文書化されます：

.. _my-project

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

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

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

そして、 このブログ投稿 に示されているようなhtml（またはpdf、latex、および他の多く）を生成します。

3
Mark Mikofski

FileExchangeにはMファイル用のDoxygen-Adapterがあります。 http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab を参照してください。

2
Wolfgang Ulmer