Main Content

创建帮助摘要文件 - Contents.m

什么是 Contents.m 文件?

Contents.m 文件提供特定文件夹中的程序的摘要。helpdoc 函数引用 Contents.m 文件以显示有关文件夹的信息。

Contents.m 文件仅包含注释行。前两行是描述该文件夹的标题。后续行列出该文件夹中的程序文件及其说明。您也可以对文件分组并包括分类说明。例如,查看位于 codetools 文件夹中的函数:

help codetools
  Commands for creating and debugging code
  MATLAB Version 9.14 (R2023a) 19-Nov-2022 
 
  Editing and publishing
    edit                   - Edit or create a file
    grabcode               - Copy MATLAB code from published HTML
    checkcode              - Check files for possible problems
    publish                - Publish file containing cells to output file
    snapnow                - Force snapshot of image for published document
  
  Directory tools
    mlintrpt               - Run mlint for file or folder, reporting results in browser
    visdiff                - Compare two files (text, MAT, or binary) or folders

   ...

如果文件夹中不存在 Contents.m 文件,则 helpdoc 函数会显示一个包含该文件夹中所有程序文件的生成列表。例如,文件夹 myfiles 包含五个程序文件,但没有 Contents.m 文件。当您对该文件夹调用 help 函数时,它会显示该文件夹中的程序文件列表以及每个文件的简要描述。

help myfiles
Contents of myfiles:

    estimatePanelOutput - Calculate Solar Time
           lengthofline - Calculates the length of a line object
        solarCorrection - The function solarCorrection calculates the difference between local and
SolarPanelEstimatorForm - is a live script.
       WeatherDashboard - is a live script.

如果不希望 helpdoc 函数显示生成列表,请在文件夹中放置一个空的 Contents.m 文件。如果文件夹包含空的 Contents.m 文件,则 helpdoc 函数会显示 foldername is a folder。如果存在另一个同名文件夹,则 helpdoc 函数会显示该同名文件夹的信息。

创建 Contents.m 文件

要自定义 helpdoc 函数显示的文件夹内容,请创建一个自定义的 Contents.m 文件。

  1. 在包含程序文件的文件夹中,创建一个名为 Contents.m 的文件。

  2. 将此模板复制到 Contents.m 文件中。

    % Folder summary
    % Version xxx dd-mmm-yyyy 
    %
    % Description of first group of files
    %   file1                   - file1 description
    %   file2                   - file2 description
    % 
    % Description of second group of files
    %   file3                   - file3 description
    %   file4                   - file4 description
  3. 修改该模板以匹配您的文件夹的内容。修改模板时,不要在第二个注释行的日期字段中包含任何空格。

    例如,下面的 Contents.m 文件描述 myfiles 文件夹的内容。

    % Folder containing my program files
    % Version 1.2.0 09-Nov-2022 
    %
    % My Functions
    %   estimatePanelOutput            - Calculate solar time
    %   lengthofline                   - Calculate the length of a line object
    %   solarCorrection                - Calculate the difference between local and solar time
    % 
    % My Live Scripts
    %   SolarPanelEstimatorForm        - Estimate solar panel output
    %   WeatherDashboard               - Display weather data for Natick, MA
  4. 您也可以在 Contents.m 文件中包含 See also 链接。要包含 See also 链接,请在文件末尾添加一行,以 % See also 开头,后跟函数名称列表。如果函数存在于搜索路径或当前文件夹中,helpdoc 函数会将其中的每个函数名称显示为指向其帮助的超链接。否则,helpdoc 函数将原样打印显示在 Contents.m 文件中的函数名称。

    例如,以下代码添加路径中的文件 myfile1.mmyfile2.mSee also 链接。

    % 
    % See also MYFILE1, MYFILE2

    您还可以在帮助文本中包含指向网站的超链接(以 URL 形式)。通过包含 HTML <a></a> 锚点元素创建超链接。在锚点内,使用 matlab: 语句执行 web 命令。

    例如,以下代码添加 MathWorks 网站的超链接。

    % For more information, see the <a href="matlab: 
    % web('https://www.mathworks.com')">MathWorks website</a>.
    

创建 Contents.m 文件后,使用 helpdoc 函数显示文件夹的内容。例如,显示 myfiles 文件夹的内容。

help myfiles
  Folder containing my program files
  Version 1.2.0 09-Nov-2022 
 
  My Functions
    estimatePanelOutput            - Calculate solar time
    lengthofline                   - Calculate the length of a line object
    solarCorrection                - Calculate the difference between local and solar time
  
  My Live Scripts
    SolarPanelEstimatorForm        - Estimate solar panel output
    WeatherDashboard               - Display weather data for Natick, MA

  See also myfile1, myfile2

  For more information, see the MathWorks website.

另请参阅

| |

相关主题