Reference

@展開

規定の属性の値に@が含まれる場合、その@を‘パッケージ名_クラス名’に置換する@展開を適用します。ただし、C言語のコメント(/*...*/)に含まれる@は展開しません。展開の対象となる属性は次の通りです。

namespace要素を指定しない場合は、次の属性の値も展開の対象となります。ただし、method要素については、class要素またはinterface要素の直接の子となる要素だけが対象となります。

識別子となる属性の値に@展開を適用した場合、展開後の文字列は識別子にならなければなりません。

a要素

包括される要素

inline.group

包括する要素

(#PCDATA)

属性

href
CDATA 必須
リンク先のURL

解説

URLにリンクする文字列です。HTMLのa要素と同様です。

abstractmethod要素

包括される要素

class

包括する要素

((param+, variableparam?)?, modifier?, return?, desc?)

属性

name
CDATA 必須 [識別子, 名前空間展開/@展開
関数の識別子

解説

【ドキュメントのみに作用します】

ドキュメントにアブストラクトメソッドのドキュメントを生成します。

ドキュメントにdesc要素の内容が展開されます。

arg要素

包括される要素

inline.group

包括する要素

(#PCDATA)

解説

引数の文字列です。イタリック体で出力します。


block.groupパラメータ実体

包括される要素

desc, li

展開される内容

p|pre|see|note|ul

解説

desc要素に含まれる要素のグループです。

brief要素

包括される要素

desc, p

包括する要素

(#PCDATA|%inline.group;)*

解説

要約となる文字列です。desc要素に含まれる最初のbrief要素の内容は要約となります。

HTML出力において、param要素またはreturn要素の内部にbrief要素を記述しても、それを通常のテキストと同様に扱います。

TeX出力ではすべてのbrief要素を通常のテキストと同様に扱います。

class要素

包括する要素

(namespace?, include*, define*, import*, export*, typedef*, (struct|union|enum)*, (method|abstractmethod)*, (globalvariable)*, desc?)

属性

name
CDATA 必須 [識別子
クラス名
package
CDATA 必須 [識別子
パッケージ名

解説

クラスのドキュメントを記述することを宣言するトップレベルの要素です。

ドキュメントにdesc要素の内容が展開されます。

code要素

包括される要素

inline.group

包括する要素

(#PCDATA)

解説

ソースコードの文字列です。タイプライタ体で出力します。


constant要素

包括される要素

enum, enummember

包括する要素

(desc?)

属性

name
CDATA 必須 [識別子, 名前空間展開/@展開
定数の識別子
value
CDATA 省略可能
定数の値

解説

ヘッダファイルで列挙型の定数を定義します。value属性の値は空文字列であってはなりません。

ドキュメントにdesc要素の内容が展開されます。

define要素

包括される要素

class

包括する要素

(macroparam*, variableparam?, macro?, desc?)

属性

name
CDATA 必須 [識別子, 名前空間展開/@展開
定義するマクロの識別子

解説

ヘッダファイルにname属性で指定したマクロを定義します。マクロの展開内容はmacro要素の内容になります。macro要素の内容が複数行で構成される場合、各行の行末にバックスラッシュを展開します。

ドキュメントにdesc要素の内容が展開されます。

desc要素

包括される要素

abstractmethod, class, constant, define, enum, enummember, export, globalvariable, interface, macroparam, member, method, package, param, return, struct, structmember, tag, typedef, union, unionmember

包括する要素

(#PCDATA|%inline.group;|%block.group;|brief|section)*

解説

各要素に対するドキュメントです。

em要素

包括される要素

inline.group

包括する要素

(#PCDATA)

解説

強調する文字列です。ボールド体で出力します。


enum要素

包括される要素

class

包括する要素

(constant+, desc?)

属性

tag
CDATA 省略可能 [識別子, 名前空間展開/@展開
列挙型のタグ名の識別子
alias
CDATA 省略可能 [識別子, 名前空間展開/@展開
typedefで定義する識別子

解説

ヘッダファイルで列挙型を定義します。alias属性を指定した場合、その名前で列挙型を型定義します。

tag属性を省略した場合は必ずalias属性を指定します。tag属性とalias属性の両方を省略することはできません。

ドキュメントにdesc要素の内容が展開されます。

enummember要素

包括される要素

nest.group

包括する要素

(constant+, tag?, desc?)

属性

tag
CDATA 省略可能 [識別子, 名前空間展開/@展開
列挙型のタグ名の識別子
name
CDATA 必須 [識別子
メンバの識別子

解説

ヘッダファイルで構造体または共用体に含まれる列挙型メンバを定義します。

tag属性を省略した場合は匿名列挙型となります。

ドキュメントにdesc要素の内容が展開されます。

この要素はmember要素とenum要素を多重継承したようなものになっています。メンバの説明はdesc要素に、定義する列挙型そのものの説明はtag要素の子のdesc要素に記述します。

export要素

包括される要素

class

包括する要素

(desc?)

属性

type
(struct|union|enum) 必須
タグのタイプ
tag
CDATA 必須 [識別子, 名前空間展開/@展開
タグの識別子

解説

ヘッダファイルに不完全な構造体、共用体、列挙型のタグを定義(構造体、共用体、列挙型の前方定義を展開)します。列挙型の前方定義はGCC拡張で使用可能です。

同じクラスに属する不透明な構造体、共用体、列挙型をそのポインタ型で参照する場合に、不完全な構造体、共用体、列挙型のタグを定義(構造体、共用体、列挙型の前方定義を展開)するために使用します。

異なるクラスに属する前方定義のタグはimport要素で記述してください。

ドキュメントにdesc要素の内容が展開されます。

globalvariable要素

包括される要素

class

包括する要素

(desc?)

属性

type
CDATA 必須 [@展開
グローバル変数の型
name
CDATA 必須 [識別子, 名前空間展開/@展開
グローバル変数の識別子

解説

ヘッダファイルでグローバル変数を定義します。type属性に#が含まれる場合、先頭の#はグローバル変数名で展開されます。

ドキュメントにdesc要素の内容が展開されます。

hyperlink要素

包括される要素

inline.group

包括する要素

(#PCDATA)

属性

label
CDATA 省略可能
ハイパーリンクのターゲット名
namespace
CDATA 省略可能
ターゲットのネームスペース

解説

ハイパーリンクのターゲットにリンクする文字列です。

同じドキュメントへのリンクではnamespace属性を省略できます。異なるクラスのターゲットにリンクする場合は、namespace属性にそのクラスの "パッケージ名.クラス名" を指定します(インタフェースも同様です)。また、パッケージのドキュメントのターゲットにリンクする場合は、namespace属性にそのクラスの "パッケージ名" を指定します。

label属性を省略した場合、namespace属性が指定するクラスまたはパッケージのドキュメントそのものにリンクします。両方の属性を省略した場合、同一ドキュメントへリンクします。

namespace属性、label属性の値が空文字列の場合、属性を省略したものとして扱います。

hypertarget要素

包括される要素

inline.group

包括する要素

(#PCDATA)

属性

label
ID 必須
ハイパーリンクのターゲット名

解説

ハイパーリンクのリンク先を定義します。

ターゲット名は1つのXMLファイル内でユニークな文字列でなければなりません。

import要素

包括される要素

class

包括する要素

EMPTY

属性

type
(struct|union|enum) 必須
タグのタイプ
tag
CDATA 必須 [@展開
タグの識別子

解説

【ヘッダファイルのみに作用します】

ヘッダファイルに不完全な構造体、共用体、列挙型のタグを定義(構造体、共用体、列挙型の前方定義を展開)します。列挙型の前方定義はGCC拡張で使用可能です。

外部で定義される(異なるクラスの)構造体、共用体、列挙型をそのポインタ型で参照する場合に、不完全な構造体、共用体、列挙型のタグを定義(構造体、共用体、列挙型の前方定義を展開)するために使用します。ただし、型の記述に含まれる構造体と共用体のタグの前方定義は自動的に出力されるので、この要素が必要になるのはマクロ定義などにより自動的に構造体、共用体のタグを発見できない場合や、GCC拡張の「不完全な列挙型」を記述する場合に限られます。

この要素のtag属性は名前空間展開の対象ではないことに注意してください。同じクラスに属する前方定義のタグはexport要素で記述してください。

include要素

包括される要素

class

包括する要素

EMPTY

属性

file
CDATA 必須
インクルードファイル名

解説

【ヘッダファイルのみに作用します】

ヘッダファイルにインクルードの指示(#include)を埋め込みます。file属性の内容が#include <>の間に展開されます。

#include "..."という形式に展開できません。

inline.groupパラメータ実体

包括される要素

brief, desc, li, note, p, see

展開される内容

code|math|arg|em|a|hypertarget|hyperlink

解説

desc要素に含まれる要素のグループです。

interface要素

包括する要素

(namespace?, method*, desc?)

属性

name
CDATA 必須 [識別子
クラス名
package
CDATA 必須 [識別子
パッケージ名

解説

【ドキュメントのみに作用します】

インタフェースのドキュメントを記述することを宣言するトップレベルの要素です。

ドキュメントにdesc要素の内容が展開されます。

li要素

包括される要素

ul

包括する要素

(#PCDATA|%inline.group;|%block.group;)*

解説

箇条書の項目を示す要素です。HTMLのli要素と同様です。


macro要素

包括される要素

define

包括する要素

(#PCDATA)

解説

【ヘッダファイルのみに作用します】

ヘッダファイルにマクロの展開内容を記述します。

macroparam要素

包括される要素

define

包括する要素

(desc?)

属性

name
CDATA 必須 [識別子
マクロの引数の識別子

解説

ヘッダファイルにマクロの引数を記述します。

ドキュメントにdesc要素の内容が展開されます。

math要素

包括される要素

inline.group

包括する要素

(#PCDATA)

解説

数式の文字列です。現在の仕様ではTeX出力では$$の間に出力します。

ハイフンをマイナス記号として出力する場合はmath要素を使用してください。

将来のバージョンとの互換性のため、英数字と空白、プラス記号、マイナス記号以外を要素に含めないようにしてください。

member要素

包括される要素

nest.group

包括する要素

(desc?)

属性

type
CDATA 必須 [@展開
メンバの型
name
CDATA 必須 [識別子
メンバの識別子

解説

ヘッダファイルで構造体または共用体のメンバを定義します。type属性に#が含まれる場合、先頭の#name属性の内容で展開されます。

ドキュメントにdesc要素の内容が展開されます。

method要素

包括される要素

class, interface, nest.group

包括する要素

((param+, variableparam?)?, modifier?, return?, desc?)

属性

name
CDATA 必須 [識別子, 名前空間展開/@展開
関数または関数ポインタの識別子

解説

ヘッダファイルに関数または関数ポインタを定義します。class要素またはinterface要素の内部では関数として、構造体または共用体のメンバでは関数ポインタとして展開されます。

この要素がclass要素またはinterface要素の直接の子である場合に限り、name属性の値に名前空間展開が適用されます。

ドキュメントにdesc要素の内容が展開されます。

modifier要素

包括される要素

abstractmethod, method

包括する要素

EMPTY

属性

code
CDATA 必須
関数の修飾子

解説

ヘッダファイルで関数または関数ポインタの修飾子を定義します。

修飾子はドキュメントにも反映されます。

namespace要素

包括される要素

class, interface

包括する要素

EMPTY

解説

この要素を指定したクラスまたはインタフェースに名前空間展開を適用します。

nest.groupパラメータ実体

包括される要素

struct, structmember, union, unionmember

展開される内容

member|structmember|unionmember|enummember|method

解説

構造体または共用体のメンバとなる要素です。

note要素

包括される要素

block.group

包括する要素

(#PCDATA|%inline.group;)*

解説

注意を示す段落の要素です。

p要素

包括される要素

block.group

包括する要素

(#PCDATA|%inline.group;|brief)*

解説

段落を示す要素です。HTMLのp要素と同様です。


package要素

包括する要素

(desc?)

属性

name
CDATA 必須 [識別子
パッケージ名

解説

【ドキュメントのみに作用します】

パッケージのドキュメントを記述することを宣言するトップレベルの要素です。

ドキュメントにdesc要素の内容が展開されます。

param要素

包括される要素

abstractmethod, method

包括する要素

(desc?)

属性

type
CDATA 必須 [@展開
引数の型
name
CDATA 必須 [識別子
引数の識別子

解説

ヘッダファイルで関数または関数ポインタの引数を定義します。type属性に#が含まれる場合、先頭の#name属性の内容で展開されます。

ドキュメントにdesc要素の内容が展開されます。

pre要素

包括される要素

block.group

包括する要素

(#PCDATA)

解説

整形済みのテキストを示す文字列です。HTMLのpre要素と同様です。

return要素

包括される要素

abstractmethod, method

包括する要素

(desc?)

属性

type
CDATA 必須 [@展開
関数の戻り値の型

解説

ヘッダファイルで関数または関数ポインタの戻り値を定義します。type属性に#が含まれる場合、先頭の#は関数または関数ポインタ名で展開されます。

ドキュメントにdesc要素の内容が展開されます。

section要素

包括される要素

desc

包括する要素

(#PCDATA)

解説

章の見出しとなる要素です。


see要素

包括される要素

block.group

包括する要素

(#PCDATA|%inline.group;)*

解説

参考または参照を示す段落の要素です。

struct要素

包括される要素

class

包括する要素

((%nest.group;)*, desc?)

属性

tag
CDATA 省略可能 [識別子, 名前空間展開/@展開
構造体のタグ名の識別子
alias
CDATA 省略可能 [識別子, 名前空間展開/@展開
typedefで定義する識別子

解説

ヘッダファイルで構造体を定義します。alias属性を指定した場合、その名前で構造体を型定義します。

tag属性を省略した場合は必ずalias属性を指定します。tag属性とalias属性の両方を省略することはできません。

ドキュメントにdesc要素の内容が展開されます。

structmember要素

包括される要素

nest.group

包括する要素

((%nest.group;)*, tag?, desc?)

属性

tag
CDATA 省略可能 [識別子, 名前空間展開/@展開
構造体のタグ名の識別子
name
CDATA 必須 [識別子
メンバ名

解説

ヘッダファイルで構造体または共用体に含まれる構造体メンバを定義します。

tag属性を省略した場合は匿名構造体となります。

ドキュメントにdesc要素の内容が展開されます。

この要素はmember要素とstruct要素を多重継承したようなものになっています。メンバの説明はdesc要素に、定義する構造体そのものの説明はtag要素の子のdesc要素に記述します。

tag要素

包括される要素

enummember, structmember, unionmember

包括する要素

(desc?)

解説

structmember要素の構造体、unionmember要素の共用体、enummember要素の列挙型に関するドキュメントを定義します。

ドキュメントにdesc要素の内容が展開されます。

typedef要素

包括される要素

class

包括する要素

(desc?)

属性

type
CDATA 必須 [@展開
識別子の型
name
CDATA 必須 [識別子, 名前空間展開/@展開
型定義する識別子

解説

ヘッダファイルにname属性で指定した名前で、type属性で指定した型を定義します。type属性に#が含まれる場合、先頭の#name属性の内容で展開されます。

ドキュメントにdesc要素の内容が展開されます。

ul要素

包括される要素

block.group

包括する要素

(li+)

解説

箇条書を示す要素です。HTMLのul要素と同様です。

union要素

包括される要素

class

包括する要素

((%nest.group;)*, desc?)

属性

tag
CDATA 省略可能 [識別子, 名前空間展開/@展開
共用体のタグ名の識別子
alias
CDATA 省略可能 [識別子, 名前空間展開/@展開
typedefで定義する識別子

解説

ヘッダファイルで共用体を定義します。alias属性を指定した場合、その名前で共用体を型定義します。

tag属性を省略した場合は必ずalias属性を指定します。tag属性とalias属性の両方を省略することはできません。

ドキュメントにdesc要素の内容が展開されます。

unionmember要素

包括される要素

nest.group

包括する要素

((%nest.group;)*, tag?, desc?)

属性

tag
CDATA 省略可能 [識別子, 名前空間展開/@展開
共用体のタグ名の識別子
name
CDATA 必須 [識別子
メンバ名

解説

ヘッダファイルで構造体または共用体に含まれる共用体メンバを定義します。

tag属性を省略した場合は匿名共用体となります。

ドキュメントにdesc要素の内容が展開されます。

この要素はmember要素とunion要素を多重継承したようなものになっています。メンバの説明はdesc要素に、定義する共用体そのものの説明はtag要素の子のdesc要素に記述します。

variableparam要素

包括される要素

abstractmethod, define, method

包括する要素

EMPTY

解説

ヘッダファイルで関数または関数ポインタまたはマクロの可変長引数を定義します。通常の引数の最後に一度だけ出現できる要素です。

名前空間展開

namespace要素を含むクラスまたはインタフェースの規定の属性の値に接頭辞‘パッケージ名_クラス名_’を付加します。名前空間展開を適用した属性の値には@展開を適用しません。ただし、@の場合は、例外的に‘パッケージ名_クラス名’に展開します。

また、展開前の属性の値が空文字列であってはなりません。

展開の対象となる属性は次の通りです。ただし、method要素については、class要素またはinterface要素の直接の子となる要素だけが対象となります。

展開後の文字列は識別子にならなければなりません。

実行時エラー

実行時に検証するエラーは次の通りです。

  • 識別子でなければならない属性の(@展開または名前空間展開前の)値が空文字列
  • 識別子でなければならない属性の(@展開または名前空間展開後の)値に、不正な文字が含まれている
  • 展開の対象となる属性の値で、C言語のコメントが属性の中で完結していない(終端がない)
  • struct要素、union要素、enum要素でtag属性とalias属性の両方が定義されていない
  • constant要素のvalue属性の内容が空文字列

エラーを検出したときはステータスコード1で終了します。

識別子

識別子は先頭が英字または_で始まり、2文字目以降が英数字または_で構成される文字列です。

次の属性の値は識別子でなければなりません。

次の属性の値も識別子でなければなりませんが、属性の値に@展開または名前空間展開を適用する場合は、展開した文字列が識別子になる必要があります。