##
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 には、呼び出しの際に使う丸括弧を含めてはなりません。 オブジェクトメソッドはこの環境で記述しません。 束縛オブジェクトメソッドをモジュールの公開インタフェースの一部として モジュールの名前空間に配置している場合、メソッドはほとんどの用途で モジュールレベル関数と等価であるため、この環境を使って記述します。

  説明には、必要なパラメタと、パラメタがどう処理されるか (とりわけ、 パラメタとして渡した変更可能なオブジェクトが変更されるか否か) 、副作用、 送出される可能性のある例外についての情報を含めねばなりません。 小規模の例題を与えてもかまいません。

`\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` に似ていますが、索引エントリを作成しません。