Yo no podía saber qué formato para escribir ayuda para su propia función de MATLAB. Muy poca información está disponible en la documentación oficial.

Qué sabe usted acerca de cualquier otro formato que puede ser visible con la Ayuda del Navegador (no con la ayuda de la función)? Como es para las funciones integradas. Cómo dar formato a los encabezados (como la Sintaxis, la Descripción, Ejemplos)? Son viñetas, tablas posible? O puede que debe ser un archivo aparte?

He tratado de marcado de texto, como se utiliza para PUBLICAR y HTML, no funciona.

Sólo he encontrado una cosa interesante. Si la función contiene mixto caso, como testHelpFunction, su nombre destacado:

MATLAB m-archivo de ayuda de formato

Resaltado No si es sólo testhelpfunction.

Cualquier otra pensamientos?

ACTUALIZACIÓN

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

Su Propia Ayuda y Demos

(Link muerto reemplazado con el archivo web link)


(Link muerto eliminado)


Actualizado de nuevo:

  • El segundo enlace que has añadido es exactamente lo que yo estaba a punto de sugerir. Cosas muy útiles allí.
  • usted debe poner su ACTUALIZACIÓN como una respuesta, y lo acepta!
  • Tengo la intención de esta pregunta, para recopilar información sobre m-archivo de formato. La creación de la documentación específica era sólo una cuestión de lado.
  • Por desgracia, ese enlace ya no funciona. Buen trabajo de MathWorks!
  • actualizado el enlace
  • Ambos links están muertos…
  • Gracias, @mangledorf! Cómo se atreve a Mathworks no mantener los links vivos. Aquí está el nuevo queridos: mathworks.com/help/matlab/matlab_prog/… y mathworks.com/help/matlab/matlab_prog/…
  • Estos nuevos vínculos parece tener mucha menos información acerca de doc comentarios 🙁

InformationsquelleAutor yuk | 2010-10-01

3 Comentarios

  1. 14

    Probar esta otra sección en la documentación oficial. Es más exhaustiva. MATLAB > Guía del Usuario > Herramientas de Escritorio y Entorno de Desarrollo > Personalización de Ayuda y Demos > Proporcionar Su Propia Ayuda y Demostraciones. Esto describe a la vez simple helptext y la generación de separar archivos de ayuda HTML.

    Aquí está el helptext formato que hemos aprendido 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 función que se llama el «H1 línea». Debe ser sólo una línea por lo que es correctamente recogido por contentsrpt(), que puede autogenerar un Contenido.m archivo de la helptext en sus funciones
    • El nombre de la función en el H1 línea es todo en mayúsculas, independientemente de su actual capitalización del nombre de la función en la firma
    • Caso los asuntos de la «Véase también». No estoy seguro de que todos los casos de trabajo; esto se hace para asegurarse.
    • Los nombres de función después de «Véase también:» están todos los caps. Los nombres de método son calificados; creo que los nombres de los métodos en la misma clase que el actual método puede ser calificado.

    Todo entre la H1 de la línea y «Ejemplos:» es sólo un formato convencional que me parece legible; (ayuda) no tratar especialmente.

    Puede utilizar una forma limitada de hipervínculos en la ayuda. En particular, se puede utilizar hipervínculos para invocar arbitraria de comandos de Matlab, y hace referencia a otras secciones de helptext por tener que invocar la ayuda(). Usted puede usar esto para señalar a ninguna función; la función «>la subfunción» es sólo la sintaxis para abordar las subfunciones en la ayuda() llamadas. Por desgracia, ya que es necesario poner «ayuda» o «doc» en los hipervínculos, que sólo funciona en una u otra forma de presentación. Sería mejor si hubo un directo helptext hipervínculo forma.

    • He decidido aceptar esta respuesta como el más completo resumen de la m-archivo de ayuda de las características de formato. Gracias, Andrew. Estoy muy de apreciar otras respuestas.
    • La sección de ayuda que usted ha mencionado parece haber desaparecido en las últimas versiones?
  2. 4

    Creo que el aspecto más importante en la ayuda de formato es que no es una ayuda a todos, y que el formato sea consistente, para que usted (y la gente que trabaja con usted) no pierdas el tiempo averiguando cómo buscar la información. Tenga en cuenta que para la programación orientada a objetos, es útil tener una superclase con una ‘ayuda’-método que llama a doc(class(obj)), puesto que no se puede fácilmente acceder a la ayuda desde una instancia de la clase

    Que me ayude a ser coherente (y para asegurarse de que no me olvido de cosas), he creado una función automática de la plantilla en el intercambio de archivos.

    Aquí está el mínimo de encabezado

    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
    %
  3. 4

    Me imagino que hay algunos (ver ejemplo), pero nunca he encontrado la documentación que corresponda. A menudo me han dicho bloques:

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

    Y la See also parte está formateado como un título, pero si reemplazar See also por otra cosa, no funciona. Si alguien encuentra la lista de títulos compatibles, por favor use el enlace aquí!

    EDITAR:

    Recientemente he llegado a aprender acerca de matlab integrado en el sistema de publicación. Parece MATLAB comentarios de apoyo de algún tipo de lenguaje de marcas no tan lejos de la Rebaja de la sintaxis (como el utilizado en LO mismo), con el apoyo de Látex ecuaciones y todo.

    Hay un post de «Loren en el arte de MATLAB» con un breve introducción en la publicación y el marcado. Para una referencia completa, ver Hacer de MATLAB para la Publicación de Comentarios en el sitio web de the Mathworks.

    Cuando el código está listo, usted puede exportar el resultado a HTML/PDF/XML, etc. el uso de la publish() función. Yo uso el siguiente fragmento de código 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);
    • gracias. Gran descubrimiento, +1. Curiosamente, «también Ver» la sección estará en la final de la ayuda en la Ayuda del Navegador. Y las funciones existentes tendrán enlaces a su página de ayuda.

Dejar respuesta

Please enter your comment!
Please enter your name here