6.3 情報単位
モジュールが提供している特定の機能を説明するために使うマクロが
数多くあります。これらの各環境には、環境を使って何を説明しようと
しているかを表す基本的な情報をパラメタに指定する必要があります。
説明内容自体は環境の中に書きます。
こうした環境のほとんどは (ドキュメントが総合索引を生成する際に)
総合索引上のエントリになります; 索引エントリが必要ない場合、
それぞれ索引を生成しない変化形の環境があります。
環境はfeaturedesc という形式の名前になり、索引を生成しない
変化形は featuredescni という形式の名前になります。
利用可能な変化形がある場合は以下のリスト内に明示しています。
各々の環境について、最初のパラメタ name は、アクセスする
機能を指定する名前です。
オブジェクトのメソッドやデータ属性といった、モジュール内の
オブジェクトのもつ機能を記述するための環境では、オプションの
type name パラメタを指定できます。
該当する機能がクラスインスタンスの属性である場合、type name
を与える必要があるのは、クラスがそのモジュールの説明で最後に説明した
クラスでない場合だけです; それ以外の場合、最後に説明した\classdesc
の name を適用します。
組み込み型や拡張型の機能については、type name を常に与えねば
なりません。もう一つ特殊なケースとして、formatter モジュールに
おける formatter や writer のような、汎用の ``プロトコル'' の
メソッドやメンバがあります: これらは特定の実装クラスなしにドキュメント
を書くことがあり、常に type name パラメタを指定する必要があります。
- \begin{cfuncdesc}
{type}{name}{args}
\end{cfuncdesc}
-
C 関数を解説するときに使う環境です。type は typedef
されている型名か、
struct tag か、基本型の名前でなければ
なりません。ポインタ型の場合、後続するアスタリスクの前にスペースを
入れてはなりません。name は関数 (または関数に似た形式をとる
プリプロセッサマクロ) の名前でなくてはならず、args にはパラメタの
型と名前を与えねばなりません。名前は説明文内でも使える形式で書かねば
なりません。
- \begin{cmemberdesc}
{container}{type}{name}
\end{cmemberdesc}
-
構造体メンバを説明するときに使う環境です。container には、
typedef されている名前ならそれを使い、そうでなければ
"struct tag" と指定せねばなりません。
メンバの型は type に指定し、メンバ名は name に指定します。
説明文中には変数の許容範囲、値がどのように解釈されるか、そして
値が変更可能かを記述せねばなりません。本文中で構造体メンバを参照する
場合には、 \member マクロを使います。
- \begin{csimplemacrodesc}
{name}
\end{csimplemacrodesc}
-
``単純'' マクロを説明するときに使う環境です。単純マクロは、
引数を取らないため関数で記述できないようなコードを展開する際に使います。
この環境は単純な定数定義には用いません。
Python ドキュメント内でのこのマクロの用例としては、
PyObject_HEAD やPy_BEGIN_ALLOW_THREADS が
あります。
- \begin{ctypedesc}
[tag]{name}
\end{ctypedesc}
-
C の型を説明するときに使う環境です。name パラメタは
typedef された名前でなければなりません。
typedef がなく、 struct で定義されている型の場合、
name は
struct tag の形式を取らねば
なりません。tag がない限りname が索引に追加されます。
tag がある場合、 tag を索引に使います。
tag は typedef された名前であってはなりません。
- \begin{cvardesc}
{type}{name}
\end{cvardesc}
-
グローバルな C の変数を説明するときに使う環境です。
type は typedef されている型名か、
struct tag か、基本型の名前でなければ
なりません。ポインタ型の場合、後続するアスタリスクの前にスペースを
入れてはなりません。
- \begin{datadesc}
{name}
\end{datadesc}
-
この環境は、モジュールにおけるグローバルなデータを説明する際に
使います。グローバルなデータには、変数と ``定義済み定数 (defined constant)''
として使われる値の両方が入ります。クラスやオブジェクト属性の記述には
この環境を使いません。
- \begin{datadescni}
{name}
\end{datadescni}
-
\datadesc に似ていますが、索引エントリを作成しません。
- \begin{excclassdesc}
{name}{constructor parameters}
\end{excclassdesc}
-
クラスとして定義されている例外を説明するために使います。
constructor parameters には、self やコンストラクタ呼び出し
構文で使う丸括弧を含めてはなりません。コンストラクタに与える
パラメタの説明がないような例外クラスを説明する場合には、
\excdesc 環境を使用してください。
- \begin{excdesc}
{name}
\end{excdesc}
-
例外を説明するための環境です。クラス例外の場合には、コンストラクタの
パラメタが記述されません: 例外クラスとコンストラクタを説明する場合には、
\excclassdesc を使ってください。
- \begin{funcdesc}
{name}{parameters}
\end{funcdesc}
-
モジュールレベルの関数を説明するための環境です。
parameters には、呼び出しの際に使う丸括弧を含めてはなりません。
オブジェクトメソッドの説明にはこの環境を使いません。
モジュールの公開インタフェースの一部としてモジュールの名前空間内に
置かれている束縛されたオブジェクトメソッド (bound object method) は、
ほとんどの用途でモジュールレベル関数と同じなので、この環境を使います。
説明には、必要なパラメタと、パラメタがどう処理されるか (とりわけ、
パラメタとして渡した変更可能なオブジェクトが変更されるか否か) 、副作用、
送出されうる例外についての情報を含めねばなりません。
小さな例題を提供してかまいません。
- \begin{funcdescni}
{name}{parameters}
\end{funcdescni}
-
\funcdesc に似ていますが、索引エントリを作成しません。
- \begin{classdesc}
{name}{constructor parameters}
\end{classdesc}
-
クラスとそのコンストラクタを説明するための環境です。
constructor parameters には、self やコンストラクタ呼び出し
構文で使う丸括弧を含めてはなりません。
- \begin{classdesc*}
{name}
\end{classdesc*}
-
コンストラクタの説明を伴わないクラスを説明するための環境です。
属性をコンテナ化することがほとんどなかったり、ユーザコードから
インスタンス化やサブクラス化を行わないようなクラスを記述する際に
利用できます。
- \begin{memberdesc}
[type name]{name}
\end{memberdesc}
-
オブジェクトのデータ属性を説明するための環境です。
説明には、想定されているデータ型や、データが直接変更可能かについての
情報がなければなりません。
- \begin{memberdescni}
[type name]{name}
\end{memberdescni}
-
\memberdesc に似ていますが、索引エントリを作成しません。
- \begin{methoddesc}
[type name]{name}{parameters}
\end{methoddesc}
-
オブジェクトメソッドを説明するための環境です。
parameters には、self パラメタや呼び出し構文で使う
丸括弧を含めてはなりません。説明には、\funcdesc 内で説明するのと
同じような情報が入っていなければなりません。
- \begin{methoddescni}
[type name]{name}{parameters}
\end{methoddescni}
-
\methoddesc に似ていますが、索引エントリを作成しません。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。
