xlabel - MATLAB m-file formato de ayuda

title graphics matlab

Question

No pude encontrar el formato disponible para escribir ayuda para su propia función MATLAB. Muy poca información está disponible en la documentación oficial .

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

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

Solo encontré una cosa interesante. Si su función contiene mayúsculas y minúsculas, como testHelpFunction , su nombre aparecerá resaltado:

Sin resaltar si solo es una función de testhelpfunction .

¿Algún otro pensamiento?

ACTUALIZAR

Aquí hay una extensa documentación que encontré sobre cómo crear tus propios archivos de ayuda:

Proporcionando tu propia ayuda y demos
(Enlace muerto reemplazado por el enlace de archivo web)

(Se eliminó el enlace muerto)

Actualizado de nuevo:

• Agregue ayuda para su programa
• Mostrar documentación personalizada

Answer 1

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 descubriendo 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 a doc(class(obj)) , ya que no puede acceder fácilmente a la ayuda desde una instancia de su clase

Para ayudarme a ser coherente (y para asegurarme de que no me olvido), he creado una plantilla de función automática en el intercambio de archivos.

Aquí está el encabezado mínimo

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
%

Answer 2

Me imagino que hay algunos (ver ejemplo), pero nunca encontré la documentación adecuada. A menudo tengo tales bloqueos:

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

Y la parte See also está formateada como 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 :

Recientemente aprendí sobre el sistema de publicación 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 una breve introducción sobre publicación y marcado. Para obtener una referencia completa, consulte Cómo crear comentarios de MATLAB para publicar en el sitio web de Mathworks.

Cuando su código esté listo, puede exportar el resultado a HTML / PDF / XML, etc. utilizando la función publish() . 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

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". Tiene que ser solo una línea, por lo que es apropiada 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 mayúscula real del nombre de la función en la firma
• El caso es importante para el "Ver también". No estoy seguro de que todos los casos funcionen; este seguro.
• Los nombres de funciones después de "Ver también:" son todos 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.