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

ヘルプ概要ファイル (`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
    mlintrpt               - Run mlint for file or folder, reporting results in browser
    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 ファイルを作成します。

プログラムファイルが含まれているフォルダーで、Contents.m という名前のファイルを作成します。

このテンプレートを 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

フォルダーの内容に合わせてテンプレートを変更します。テンプレートを変更する際には、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

オプションで、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.

参考

doc | help | ver

Contents.m ファイルとは

Contents.m ファイルの作成

参考

関連するトピック