バージョン: 20 R5 BETA

ドキュメンテーション

アプリケーションプロジェクトにおいては、メソッドやクラス、フォーム、テーブル、フィールドに関するドキュメンテーションを作成することができます。複数のプログラマーによってプロジェクトを開発している場合などに、ドキュメンテーションの作成はとくに適しています。また、一般的に良いプログラミングの作法としても推奨されます。ドキュメンテーションには、要素の説明だけでなく、アプリケーションにおけるその要素の機能を理解するために必要なあらゆる情報を含めることができます。

ドキュメントすることができるプロジェクト要素は次のとおりです:

メソッド (データベースメソッド、コンポーネントメソッド、プロジェクトメソッド、フォームメソッド、4D Mobile メソッド、トリガー)
クラス
Forms
テーブルとフィールド

ドキュメンテーションファイルは Markdown記法 (.md ファイル) で記述します。これには、Markdown をサポートしている任意のエディターを使うことができます。これらはそれぞれ独立したファイルとしてプロジェクトフォルダー内に格納されます。

ドキュメントされた内容は、エクスプローラーの右側にあるプレビューエリアに表示されます:

It can also be partially exposed as code editor tips.

ドキュメンテーションファイル

ドキュメンテーションファイル名

ドキュメンテーションファイルには、ドキュメントの対象である要素と同じファイル名が付き、拡張子は ".md" です。 For example, the documentation file attached to the myMethod.4dm project method will be named myMethod.md.

エクスプローラー上では、選択した要素と同じファイル名のドキュメンテーションが自動的に表示されます (後述参照)。

ドキュメンテーションファイルのアーキテクチャー

All documentation files are stored in the Documentation folder, located at the first level of the package folder.

The Documentation folder architecture is the following:

ドキュメント
- Classes
  - myClass.md
- DatabaseMethods
  - onStartup.md
  - ...
- フォーム
  - loginDial.md
  - ...
- Methods
  - myMethod.md
  - ...
- TableForms
  - 1
    - input.md
    - ...
  - ...
- トリガー
  - table1.md
  - ...
プロジェクトフォームとそのプロジェクトフォームメソッドは、同じドキュメンテーションファイルをフォームとメソッドの両方について共有します。
テーブルフォームとそのテーブルフォームメソッドは、同じドキュメンテーションファイルをフォームとメソッドの両方について共有します。

ドキュメントされているプロジェクト要素を名称変更したり、削除したりすると、その要素に紐づいている Markdown ファイルも自動で名称変更、または削除されます。

エクスプローラーとドキュメンテーション

ドキュメンテーションの表示

エクスプローラーウィンドウにドキュメンテーションを表示させるには:

プレビューエリアが表示されていることを確認します。
エクスプローラーリストより、ドキュメントされている要素を選択します。
Click the Documentation button located below the preview area.

If no documentation file was found for the selected element, a Create button is displayed (see below).
選択要素のドキュメンテーションファイルが存在すれば、その内容がエリア内に表示されます。なお、エリアに表示されている内容は直接編集することはできません。

ドキュメンテーションファイルの編集

選択要素の Markdown ドキュメンテーションファイルはエクスプローラーより作成・編集することができます。

選択要素のドキュメンテーションファイルが存在しなければ:

click on the Create button in the Documentation pane or,
choose the Edit Documentation... option in the contextual menu or options menu of the Explorer.

テンプレートを使い、適切な場所・名称で自動作成された .md ファイルは、デフォルトの Markdown エディターで開かれます。

If a documentation file already exists for the selected element, you can open it with your Markdown editor by choosing the Edit Documentation... option in the contextual menu or options menu of the Explorer.

コードエディターでドキュメンテーションを表示する

4D のコードエディターは、メソッドのドキュメンテーションの一部をヘルプTip として表示します。

If a file named \<MethodName>.md exists in the \<package>/documentation folder, the code editor displays (by priority):

Any text entered in an HTML comment tag () at the top of the markdown file.
Or, if no html comment tag is used, the first sentence after a # Description tag of the markdown file.\ In this case, the first line contains the prototype of the method, automatically generated by the 4D code parser.

注

Otherwise, the code editor displays the block comment at the top of the method code.

ドキュメンテーションファイルの定義

4D はテンプレートを用いて新規のドキュメンテーションファイルを作成します。 This template suggests specific features that allow you to display information in the code editor.

However, you can use any supported Markdown tags.

新規作成されたドキュメンテーションファイルには、次のデフォルト項目が含まれています:

線	説明
`<!-- ここに概要を入力します -->`	HTML コメントタグ。 Used in priority as the method description in the code editor tips
## Description	Markdown のレベル2 見出しタグ。 HTML コメントタグが使用されていない場合、このタグ後の最初の文章がメソッドの説明としてコードエディターTip に表示されます。
## Example	レベル2 見出しタグ。サンプルコードの記述に使用できます。
```4d Type here your example```	4D サンプルコードのフォーマットに使います (highlight.js ライブラリを使用)。

サポートされている Markdown

見出しタグ:

# 見出し 1
## 見出し 2
### 見出し 3

スタイルタグ (イタリック、太字、取り消し線) :

_イタリック_
**太字**
**_太字/イタリック_**
~~取り消し線~~

The code block tag (`4d ... `) is supported with 4D code highlight:

```4d
    var $txt : Text
    $txt:="Hello world!"  
```

テーブルタグ:

| 引数 | 型   | 説明  |
| --------- | ------ | ------------ |
| wpArea    | 文字列 |Write pro エリア|
| toolbar   | 文字列 |ツールバー名  |

リンクタグ:

// Case 1
The [documentation](https://doc.4d.com) of the command ....

// Case 2
[4D blog][1]

[1]: https://blog.4d.com

画像タグ:

![画像の説明](pictures/image.png)

![4D ロゴ](https://blog.4d.com/wp-content/uploads/2016/09/logoOrignal-1.png "4D blog logo")

[![4D ブログのロゴとリンク](https://blog.4d.com/wp-content/uploads/2016/09/logoOrignal-1.png "4D blog logo")](https://blog.4d.com)

For more information, see the GitHub Markdown guide.

例題

In the WP SwitchToolbar.md file, you can write:

<!-- This method returns a different logo depending on the size parameter -->


GetLogo (size) -> logo


| Parameter | Type   | in/out | Description |
| --------- | ------ | ------ | ----------- |
| size      | Longint | in | Logo style selector (1 to 5)  |
| logo      | Picture | out | Selected logo |


## Description

This method returns a logo of a specific size, depending on the value of the *size* parameter.
1 = smallest size, 5 = largest size.

## Example

```4d
C_PICTURE($logo)
C_LONGINT($size)

//Get the largest logo
$logo:=GetLogo(5)
```

エクスプローラーの表示:

コードエディターの表示:

ドキュメンテーションファイル​

ドキュメンテーションファイル名​

ドキュメンテーションファイルのアーキテクチャー​

エクスプローラーとドキュメンテーション​

ドキュメンテーションの表示​

ドキュメンテーションファイルの編集​

コードエディターでドキュメンテーションを表示する​

ドキュメンテーションファイルの定義​

サポートされている Markdown​

例題​