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

什么是 Contents.m 文件？

Contents.m 文件提供特定文件夹中的程序的摘要。help 和 doc 函数引用 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
    visdiff                - Compare two files (text, MAT, or binary) or folders

   ...

如果文件夹中不存在 Contents.m 文件，则 help 和 doc 函数会显示一个包含该文件夹中所有程序文件的生成列表。例如，文件夹 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.

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

创建 Contents.m 文件

要自定义 help 和 doc 函数显示的文件夹内容，请创建一个自定义的 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 开头，后跟函数名称列表。如果函数存在于搜索路径或当前文件夹中，help 和 doc 函数会将其中的每个函数名称显示为指向其帮助的超链接。否则，help 和 doc 函数将原样打印显示在 Contents.m 文件中的函数名称。

    例如，以下代码添加路径中的文件 myfile1.m 和 myfile2.m 的 See 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 文件后，使用 help 和 doc 函数显示文件夹的内容。例如，显示 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.

另请参阅

| |

主题