ऑब्जेक्ट उन्मुख MATLAB कोड कैसे दस्तावेज़ित करें?

Question

मैं ऑब्जेक्ट उन्मुख MATLAB का उपयोग करके एक बड़ा एप्लीकेशन लिख रहा हूं, और इसने मुझे कोड को दस्तावेज़ित करने के बारे में सोचने के बारे में सोचा है। यदि यह सी था, तो मैं डॉक्सीजन का उपयोग करूंगा। जावा के लिए, मैं जावाडोक का उपयोग करता हूं। क्लास और विधि प्रलेखन को किस प्रकार दिखाना चाहिए और इसमें क्या होना चाहिए, इसके लिए मानक दोनों मानते हैं।

लेकिन MATLAB कोड के बारे में क्या? मैंने टीएमडब्ल्यू की अपनी कक्षाओं में सबसे ज्यादा देखा है कक्षा के शीर्ष पर एक छोटी सी वाक्य या दो है, और मुझे बड़े MATLAB अनुप्रयोगों को दस्तावेज करने के लिए समर्पित कोई भी विषय नहीं मिल रहा है।

तो आप अपने MATLAB कक्षाओं को कैसे दस्तावेज़ित करते हैं? कोई विशेष शैली के मुद्दों या अतिरिक्त उपकरण?

Answer 1

मुझे एहसास है कि सवाल पुराना है, लेकिन Google के लाभ के लिए: मैटलैब के लिए एक अंतर्निहित सुविधा है। आप अपनी टिप्पणियां एक निश्चित शैली (ला जावाडोक) में लिखते हैं और वे मदद और दस्तावेज़ कार्यों द्वारा उठाए जाते हैं। इसका उपयोग कक्षाओं, गुणों और विधियों को दस्तावेज करने के लिए किया जा सकता है। यह आश्चर्यजनक रूप से पूरा है, फिर भी थोड़ा मुश्किल है। डॉक यहाँ है:

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

Answer 2

मैं अपने ऊ कोड निम्न प्रकार के दस्तावेज:

1. फ़ाइल है कि 'classdef' शामिल की शुरुआत में, मैं और सामान्य उपयोग क्या वर्ग करता है का एक सारांश, लिखें। मैं गुणों को विस्तार से समझाता हूं और मैं प्रत्येक विधि का 1-वाक्य विवरण जोड़ता हूं।
2. प्रत्येक संपत्ति परिभाषा के बाद, मैं इसके बारे में एक व्याख्यात्मक वाक्य (उसी पंक्ति पर)
3. प्रत्येक विधि को एक फ़ंक्शन की तरह दस्तावेज किया गया है, यानी इसमें एच 1-लाइन, एक सारांश है, और इनपुट का स्पष्टीकरण है और आउटपुट पैरामीटर।

जब आप 'डॉक्टर myClass' कहते हैं, तो आप शुरुआत में (1) देखेंगे, इसके बाद आपके द्वारा जोड़े गए वाक्य (2) में वर्णित गुणों की सूची और एच 1- लाइन और बाकी सहायता (3) यदि आप लिंक पर क्लिक करते हैं।

इसके अलावा, मेरे सभी वर्ग एक सामान्य सुपरक्लास को उपclass करते हैं जो विधि (सहायता) को विधि (सहायता) कहते हैं जो दस्तावेज़ (कक्षा (ओबीजे)) कहता है, जो मुझे कक्षा के हर उदाहरण से सहायता लाने की अनुमति देता है।

उदाहरण

%# 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 आप एक अच्छे एचटीएमएल प्रलेखन चाहते हैं, आप के अलावा, m2html का उपयोग आप के लिए यह उत्पन्न करने के लिए कर सकते हैं। एम 2 एचटीएमएल सहायता ग्रंथों को एकत्र करेगा और यह निर्भरता ग्राफ भी कर सकता है।

संपादित करें 2 जबकि एम 2 एचटीएमएल मानक मानक मैटलैब कोड अच्छी तरह से रखते हैं, इसकी कक्षाओं के लिए कोई विशिष्ट समर्थन नहीं है। इसका मतलब यह है कि आपको क्लास में जुड़े 'सबफंक्शन' के रूप में विधियां मिलती हैं, लेकिन आपको डॉक्सिजन के साथ मिलते-जुलते सारांश के रूप में अच्छा नहीं मिलता है, या जिसे आप अंतर्निहित दस्तावेज़ ब्राउज़र के साथ प्राप्त करते हैं।

Answer 3

फ़ाइल एक्सचेंज पर एम-फाइल्स के लिए एक डॉक्सीजन-एडाप्टर मौजूद है, http://www.mathworks.com/matlabcentral/fileexchange/25925-using-doxygen-with-matlab देखें।

Answer 4

matlabdomain विस्तार के साथ Sphinx की कोशिश करो। स्फिंक्स Python पैकेज है जो ReStructuredText (rst) markup का उपयोग कर ऑटो-दस्तावेज़ कोड है।एक्सटेंशन sphinxcontrib-matlabdomain MATLAB कोड के ऑटो-प्रलेखन की अनुमति देता है जो स्फिंक्स द्वारा अपने डॉकस्ट्रिंग में मान्यता प्राप्त आरएसटी मार्कअप का उपयोग करता है। issue tracker on 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 (या पीडीएफ, लेटेक्स, और कई अन्य लोगों का उत्पादन होगा) जैसा कि this blog post पर दिखाया गया है।