どうも久しぶりに覗いてみると、uim API の documentation が見当たらないん
ですが、あるんでしょうか。ある場合、code との整合性はとれてるんでしょう
か。
私としては、entry point にあたる API に comment を入れて、Doxygen あた
り documentation を生成するのが一番いいと思うんですが、そういう事をする
予定はありますか?
例えば、最近見つけた mlterm の bug では、uim_get_default_im_name() の返
り値が次の API call で無効化されることが mlterm の開発陣に伝わっていま
せんでした。これを例えば、
/**
* Returns the name of the default input method associated with a
* given locale. The memory region occupied by the returned string
* may be free()'ed on any subsequent call to a uim API. The caller
* must immediately copy the returned string in order to safely refer
* to it later on.
*
* @param localename A string describing the locale whose default IM
* is to be retrieved.
*/
const char *
uim_get_default_im_name(const char *localename)
{
...
}
みたいに書いておいて doxygen 化したものを wiki に置いとくのは、uim 内外
で仕様が明確になって良いと思うんですが、どうでしょう。
なお、文書生成 tool ですが、ちょっと探した範囲では
- C に使えて
- global concern を書きやすい
ものでは doxygen 一択のようです。ここで global concern というのは、例え
ば uim が返す文字列などの buffer というのは uim_get_default_im_name()
に限らず、「基本的に次の API call までは有効で、それ以降は使用不可」と
いうのが default だと思います。そういう基本的な policy を、特定の関数な
どに関連付けること無く章立てて書かせてくれる (らしい) という意味です。
--~--~---------~--~----~------------~-------~--~----~
Google Groups "uim-ja" group
uim-ja@googlegroups.com
http://groups.google.com/group/uim-ja/about
-~----------~----~----~----~------~----~------~--~---
