객체 지향 MATLAB 코드를 문서화하는 방법은 무엇입니까?

Question

저는 객체 지향 MATLAB을 사용하여 상당한 규모의 응용 프로그램을 작성하고 있습니다. 따라서이 코드를 문서화하는 방법에 대해 생각하게되었습니다. 이것이 C라면 Doxygen을 사용합니다. Java의 경우 JavaDoc을 사용합니다. 둘 다 대부분 클래스 및 메소드 문서가 어떻게 나타나야하고 그것이 포함되어야하는지에 대한 합의 표준을 가지고 있습니다.

하지만 MATLAB 코드는 어떻게됩니까? TMW의 고유 한 클래스에서 가장 많이 본 것은 클래스 상단의 짧은 문장 또는 2 개이며 대용량 MATLAB 응용 프로그램을 문서화하는 데 필요한 주제를 찾을 수 없습니다.

그래서 어떻게 MATLAB 클래스를 문서화합니까? 특정 스타일 문제 또는 추가 도구?

Answer 1

나는이 질문이 부실하다는 것을 알고 있지만, Google의 이익을 위해 : Matlab에 내장 된 기능이 있습니다. 주석을 특정 스타일 (JavaDoc)로 작성하면 도움말 및 doc 함수에 의해 주석이 선택됩니다. 클래스, 속성 및 메서드를 문서화하는 데 사용할 수 있습니다. 그것은 놀랍게도 완성되었지만 조금 까다 롭습니다. 해당 문서는 여기에 있습니다 :

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

Answer 2

내가 내 OO 코드를 다음과 같은 방법으로 문서화 'classdef'를 포함하는 파일의 시작 부분에서

1. , 나는 클래스가하는 일의 요약 및 일반적인 사용 물품. 또한 속성을 자세히 설명하고 각 메서드에 대한 1 문장 설명을 추가합니다.
2. 각 속성 정의 다음에는 하나의 설명 문장을 추가합니다 (같은 줄에)
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 

편집 한 당신이 좋은 HTML 문서를 원하는 경우에, 당신은뿐만 아니라, 당신을 위해 그것을 생성 할 m2html를 사용할 수 있습니다. M2html은 도움말 텍스트를 수집 할 것이고 의존성 그래프도 할 수 있습니다.

편집 2 m2html은 표준 Matlab 코드를 훌륭하게 문서화하지만 클래스에 대해서는 특별히 지원하지 않습니다. 즉, 클래스에서 링크 된 '하위 함수'로 메소드를 가져 오지만 Doxygen을 사용하거나 내장 된 문서 브라우저로 얻을 수있는 요약 정보를 얻을 수는 없습니다.

Answer 3

FileExchange에 M 파일 용 Doxygen 어댑터가 있습니다 (http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab 참조).

Answer 4

가 matlabdomain 확장자 Sphinx을보십시오. Sphinx는 Python 패키지이며 ReStructuredText (rst) markup을 사용하여 코드를 자동 문서화합니다.확장 sphinxcontrib-matlabdomain은 docstring에서 Sphinx가 인식 한 첫 번째 마크 업을 사용하는 MATLAB 코드의 자동 문서화를 허용합니다. issue tracker on BitBucket에 버그 및 제안 보내기

예를 들어, my_project/my_fun.m에 다음 코드 :

.. _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, 라텍스, 그리고 많은 다른 사람을 생산할 것 :

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 

이 같은 첫 번째 파일에 기록 될 것이다) this blog post에 표시된 것과 같습니다.