このプロジェクトのAPIリファレンスの記述ポリシーを説明します。
オブジェクトの参照の引数
メソッド呼び出しで引数として渡すオブジェクトの参照には次のようなタイプがあります。
それぞれのタイプによって、ドキュメントに記述される内容が次のように異なります。
オブジェクトへのアクセスはメソッド呼び出しの間にだけ発生し、呼び出しから戻った後はアクセスされません（もちろん、呼び出しによってオブジェクトは複製されたり参照カウントを増やされている可能性がありますが、そのことは呼び出し元が関知することではありません）。したがって、メソッド呼び出し後に、呼び出し元がオブジェクトを変更、解放しても、呼び出したメソッドのクラスやインスタンスに影響はありません。
オブジェクトへの参照が発生する期間がドキュメントに特に記述されない場合は、このタイプの参照になります。このタイプの参照であることをドキュメントに明記したい場合、次のようなスタイルで記述します。
例: strlen(3)
メソッド呼び出し後も、呼び出したメソッドのクラスやインスタンスがオブジェクトにアクセスします。ケースによっては、メソッド呼び出し後に呼び出し元がオブジェクトを操作することを制限したり、呼び出したメソッドのクラスやインスタンスがオブジェクトを解放することもあります。
オブジェクトへのアクセスが発生しなくなる操作や、オブジェクトへの参照が発生する期間について、次のようなスタイルでドキュメントに記述しなければなりません。オブジェクトの操作に制限がある場合や、オブジェクトが解放されてしまう場合は、それも併せて記述しなければなりません。
例: setvbuf(3), pthread_attr_setstackaddr(3)
メソッド呼び出し後は呼び出し元がオブジェクトにアクセスすることができなくなります。典型的な例はデストラクタです。戻り値などによってオブジェクトへのアクセスの可否が決まる場合もあります。
オブジェクトを参照できなくなってしまう条件を、次のようなスタイルでドキュメントに記述しなければなりません。
例: free(3), realloc(3)
オブジェクトの参照の戻り値
メソッド呼び出しで戻り値として返すオブジェクトの参照には次のようなタイプがあります。
それぞれのタイプによって、ドキュメントに記述される内容が次のように異なります。
このタイプの参照は主にget系のメソッドによって返されます。取得したオブジェクトは、呼び出したメソッドのクラスまたはインスタンスが参照しています。取得したオブジェクトは呼び出し元による変更や解放などの操作が制限されているかもしれません。必要があれば、呼び出し元は取得したオブジェクトを複製しなければなりません。
取得したオブジェクトが有効な期間、制限を次のようなスタイルでドキュメントに記述しなければなりません。
例: 4.4BSDのfgetln(3)
このタイプの参照は主にcreate系のメソッドやコンストラクタによって返されます。呼び出したメソッドのクラスまたはインスタンスは生成したオブジェクトを参照していません（ただし、戻り値が参照するオブジェクトが自分を生成したインスタンスを参照していることがあり、その場合は別の制限が加わります）。呼び出し元は、戻り値が参照するオブジェクトが不要になったとき（を参照しなくなるとき）に、それを解放する必要があります。
生成したオブジェクトを解放する方法を次のようなスタイルでドキュメントに記述しなければなりません。
例: strdup(3)
このタイプの参照は主にstrchr(3)のような探索系のメソッドによって返されます（特に文字列は文字配列として同様に扱います）。引数の配列オブジェクトの要素を選択し、その要素の参照を返します。一般に、引数の型にconst修飾子が指定されていても、戻り値には指定されません。
このタイプの参照は、次のようなスタイルでドキュメントに記述しなければなりません。
例: strchr(3)
クラスの初期化
主にstaticInitialize系のメソッドで初期化します。環境によってはAPI利用者が明示的に呼び出す必要がないかもしれません（スタートアップコードが自動的にmainよりも先に呼び出すため）。
ドキュメントには次のようなスタイルで記述しなければなりません。
実装上の都合で公開されるメソッド
ドキュメントには次のようなスタイルで記述しなければなりません。