MATLAB m-file help formatting

Question

Non sono riuscito a trovare quale formattazione disponibile per scrivere aiuto per la propria funzione MATLAB. Sono disponibili pochissime informazioni in official documentation.

Conoscete qualsiasi altra formattazione che può essere visibile con il browser della guida (non con la funzione di guida)? Come è per le funzioni integrate. Come formattare le intestazioni (come Sintassi, Descrizione, Esempi)? I proiettili sono possibili? O potrebbe essere dovrebbe essere un file separato?

Ho provato il markup di testo come utilizzato per PUBLISH e HTML, non ha funzionato.

Ho trovato solo una cosa interessante. Se la funzione contiene lettere maiuscole e minuscole, come testHelpFunction, il suo nome sarà evidenziato:

No evidenziazione se è solo testhelpfunction.

Qualche altra idea?

UPDATE

Ecco un'ampia documentazione che ho trovato sulla creazione di file di aiuto:

Providing Your Own Help and Demos
(Dead link sostituito con il collegamento archivio web)

---

(link morto rimosso)

---

nuovamente aggiornato:

• Add Help for Your Program
• Display Custom Documentation

Answer 1

Prova questa altra sezione nella documentazione ufficiale. È più completo. MATLAB> Manuale dell'utente> Strumenti desktop e ambiente di sviluppo> Personalizzazione di guida e demo> Fornire la propria guida e demo. Descrive sia il semplice testo della guida che la generazione di file di guida HTML separati.

Ecco la formattazione del testo che ho trovato e che ho trovato utile.

function foo(x,y,z) 
%FOO One-line description goes here 
% 
% foo(x,y,z) 
% 
% Multi-line paragraphs of descriptive text go here. It's fine for them to 
% span lines. It's treated as preformatted text; help() and doc() will not 
% re-wrap lines. In the editor, you can highlight paragraphs, right-click, 
% and choose "Wrap selected comments" to re-flow the text. 
% 
% More detailed help is in the <a href="matlab: help foo>extended_help">extended help</a>. 
% It's broken out like this so you can keep the main "help foo" text on 
% a single screen, and then break out obscure parts to separate sections. 
% 
% Examples: 
% foo(1,2,3) 
% 
% See also: 
% BAR 
% SOMECLASS/SOMEMETHOD 

disp(x+y+z); 

function extended_help 
%EXTENDED_HELP Some additional technical details and examples 
% 
% Here is where you would put additional examples, technical discussions, 
% documentation on obscure features and options, and so on. 

error('This is a placeholder function just for helptext'); 

• La prima riga dopo la firma funzione viene chiamata la "linea H1". Deve essere solo una riga quindi viene prelevata correttamente da contentsrpt(), che può generare automaticamente un file Contents.m dal testo della guida nelle tue funzioni
• Il nome della funzione nella riga H1 è tutto maiuscolo, indipendentemente dalla capitalizzazione effettiva del nome della funzione nella firma
• Il caso vale per "Vedere anche". Non sono sicuro di tutti i casi che funzionano; questo è sicuro.
• I nomi delle funzioni dopo "Vedi anche:" sono tutti maiuscoli. I nomi dei metodi sono qualificati; Penso che nomi di metodi nella stessa classe del metodo attuale possano essere non qualificati.

Tutto tra la riga H1 e "Esempi:" è solo una formattazione convenzionale che trovo leggibile; help() non lo tratta in modo speciale.

È possibile utilizzare una forma limitata di collegamenti ipertestuali in Guida. In particolare, è possibile utilizzare i collegamenti ipertestuali per invocare comandi Matlab arbitrari e puntare ad altre sezioni del testo della guida invocando help(). Puoi usare questo per indicare qualsiasi funzione; "funzione> sottofunzione" è solo la sintassi per indirizzare le sottofunzioni nelle chiamate help(). Sfortunatamente, poiché è necessario inserire "help" o "doc" in tali collegamenti ipertestuali, funziona solo nell'uno o nell'altro modulo di presentazione. Sarebbe più bello se ci fosse un modulo di collegamento ipertestuale a helptext diretto.

Answer 2

immagino che ci sia qualche (vedi esempio), ma non ho mai trovato la documentazione appropriata. Ho spesso tali blocchi:

% ... 
% 
% See also: 
% this_other_function() 
% 
% <author> 

E la parte See also è formattato come un titolo, ma se si sostituisce See also da qualcos'altro, non funziona. Se qualcuno trova l'elenco di tali titoli supportati, collegalo qui!

EDIT:

ho recentemente venuto a conoscere sistema di pubblicazione integrato di MATLAB. Sembra che i commenti di MATLAB supportino qualche forma di markup non molto lontano dalla sintassi di Markdown (come quella usata da SO stesso), con il supporto per le equazioni di LaTeX e tutto il resto.

C'è un post di "Loren sull'arte di MATLAB" con uno short introduction su pubblicazione e markup. Per un riferimento completo, vedere Making Up MATLAB Comments for Publishing sul sito Web di Mathworks.

Quando il codice è pronto, è possibile esportare il risultato in HTML/PDF/XML, ecc. Utilizzando publish() function.Io uso il seguente frammento per esportare i miei file:

% Other formats are supported, refer to documentation. 
options.format = 'html'; 

    % I don't evaluate the code, especially for functions that require arguments. 
    % However, if providing a demo, turning this on is a fantastic way to embed 
    % figures in the resulting document. 
options.evalCode = false; 

    % You can run this in a loop over files in the currrent directory if desired. 
publish('script.m', options); 

Answer 3

Penso che l'aspetto più importante della formattazione della guida sia l'assenza di aiuto e la coerenza della formattazione, in modo che tu (e le persone che lavorano con te) non perdi tempo a cercare il modo di cercare l'informazione. Si noti che per OOP, è utile avere una superclasse con un 'metodo help' che chiama doc(class(obj)), dal momento che non è possibile accedere facilmente l'aiuto di un'istanza della classe

di aiutarmi a essere coerente (e per assicurarsi Non dimentico le cose), ho creato uno automatic function template sullo scambio di file.

Ecco l'intestazione minima

function testhelp 
%TESTHELP is an example (this is the H1 line) 
% 
% SYNOPSIS: a=testhelp(b,c) 
% 
% INPUT b: some input parameter 
%  c: (opt) some optional input parameter. Default: [] 
% 
% OUTPUT a: some output parameter 
% 
% REMARKS This is just an example, it won't run 
% 
% SEE ALSO testHelpFunction 
% 
% created with MATLAB ver.: 7.11.0.584 (R2010b) on Mac OS X Version: 10.6.4 Build: 10F569 
% 
% created by: Jonas 
% DATE: 01-Oct-2010 
%