MATLAB m-file help formatting

Question

No pude encontrar el formato disponible para escribir ayuda para su propia función MATLAB. Muy poca información está disponible in official documentation.

¿Conoce algún otro formato que pueda verse con el Explorador de Ayuda (no con la función de ayuda)? Como es para funciones integradas. ¿Cómo formatear títulos (como Sintaxis, Descripción, Ejemplos)? ¿Son posibles las balas y las mesas? ¿O puede ser un archivo separado?

He intentado el marcado de texto como se utiliza para PUBLISH y HTML, no funcionó.

Encontré solo una cosa interesante. Si su función contiene mayúsculas y minúsculas, como testHelpFunction, se resaltará su nombre:

No se puede resaltar si es sólo testhelpfunction.

¿Alguna otra idea?

ACTUALIZACIÓN

Aquí es extensa documentación que encontré en la creación de sus propios archivos de ayuda:

Providing Your Own Help and Demos
(vínculo roto reemplazado por enlace de archivo web)

---

(vínculo roto eliminado)

---

actualizado de nuevo:

• Add Help for Your Program
• Display Custom Documentation

Answer 1

Pruebe esta otra sección en la documentación oficial. Es más completo. MATLAB> Guía del usuario> Herramientas de escritorio y entorno de desarrollo> Personalización de ayuda y demostraciones> Proporcionar su propia ayuda y demostraciones. Esto describe tanto el texto de ayuda simple como la generación de archivos de ayuda HTML separados.

Aquí está el formato de texto de ayuda que he recogido y encontrado útil.

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 primera línea después de la firma de la función se llama la "línea H1". Necesita ser solo una línea para que sea apropiadamente recogida por contentsrpt(), que puede autogenerar un archivo Contents.m desde el texto de ayuda en sus funciones
• El nombre de la función en la línea H1 es mayúscula, independientemente de la capitalización real del nombre de la función en la firma
• El caso es importante para "Ver también". No estoy seguro de que todos los casos funcionen; este seguro.
• Los nombres de las funciones después de "Ver también:" son todas mayúsculas. Los nombres de los métodos están calificados; Creo que los nombres de los métodos en la misma clase que el método actual no pueden ser calificados.

Todo lo que hay entre la línea H1 y "Ejemplos:" es simplemente un formato convencional que me parece legible; help() no lo trata especialmente.

Puede usar una forma limitada de hipervínculos como ayuda. En particular, puede usar hipervínculos para invocar comandos arbitrarios de Matlab y señalar otras secciones de texto de ayuda haciendo que invoque help(). Puede usar esto para apuntar a cualquier función; "función> subfunción" es solo la sintaxis para abordar subfunciones en llamadas de ayuda(). Desafortunadamente, como necesita colocar "ayuda" o "doc" en esos hipervínculos, solo funciona en uno u otro formulario de presentación. Sería más agradable si hubiera un formulario de hipervínculo de texto de ayuda directo.

Answer 2

Calculo hay alguna (véase el ejemplo), pero nunca he encontrado la documentación apropiada. A menudo tengo tales bloques:

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

Y la parte See also tiene el formato de un título, pero si reemplaza See also por otra cosa, no funciona. Si alguien encuentra la lista de dichos títulos compatibles, ¡conéctelo aquí!

EDITAR:

he llegado recientemente a aprender sobre el sistema editorial integrado de MATLAB. Parece que los comentarios de MATLAB admiten alguna forma de marcado no muy lejos de la sintaxis de Markdown (como se usa en SO en sí), con soporte para ecuaciones LaTeX y todo.

Hay una publicación de "Loren sobre el arte de MATLAB" con un short introduction sobre publicación y marcado. Para obtener una referencia completa, consulte Making Up MATLAB Comments for Publishing en el sitio web de Mathworks.

Cuando su código esté listo, puede exportar el resultado a HTML/PDF/XML, etc. utilizando el publish() function.Uso el siguiente fragmento para exportar mis archivos:

% 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

Creo que el aspecto más importante en el formato de ayuda es que hay una ayuda y que el formato es coherente, para que usted (y las personas que trabajan con usted) no pierdan el tiempo buscando cómo buscar. la información. Tenga en cuenta que para OOP, es útil tener una superclase con un método de 'ayuda' que llame al doc(class(obj)), ya que no puede acceder fácilmente a la ayuda desde una instanciación de su clase

Para ayudarme a ser coherente (y asegurarse No me olvido de cosas), he creado un automatic function template en el intercambio de archivos.

Aquí está la cabecera mínima

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 
%