ヘルプ概要ファイル (Contents.m) の作成

Contents.m ファイルとは

Contents.m ファイルは特定フォルダーのプログラムの概要を提供します。関数 help および doc は、Contents.m ファイルを参照してフォルダーの情報を表示します。

Contents.m ファイルには、コメント行のみが含まれています。最初の 2 行はフォルダーを説明するヘッダーです。それに続く行では、フォルダー内のプログラム ファイルを説明とともにリストします。オプションとして、ファイルをグループ化してカテゴリの説明を含めることができます。たとえば、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 に 5 つのプログラム ファイルが含まれているが、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. フォルダーの内容に合わせてテンプレートを変更します。テンプレートを変更する際には、2 つ目のコメント行の日付フィールドにスペースを含めないでください。

    たとえば、この 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. オプションで、See also リンクを Contents.m ファイルに含めることもできます。See also リンクを含めるには、% See also で始まり、その後に関数名のリストが続く行をファイルの最後に追加します。関数が検索パス上か現在のフォルダー内にある場合は、関数 help および doc は、これらの各関数名をそのヘルプへのハイパーリンクとして表示します。そうでない場合は、関数 help および doc は、Contents.m ファイルに記述されているとおりに関数名を出力します。

    たとえば、以下のコードでは See also リンクをファイル myfile1.m および myfile2.m に追加しています。これらのファイルはパス上にあります。

    % 
% See also MYFILE1, MYFILE2

    ヘルプ テキストに、Web サイトへのハイパーリンクを (URL の形式で) 含めることもできます。HTML <a></a> アンカー要素を含めてハイパーリンクを作成します。アンカー内で、matlab: ステートメントを使用して web コマンドを実行します。

    たとえば、以下のコードでは MathWorks の Web サイトへのハイパーリンクを追加しています。

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

参考

| |

トピック