Doxygen もっと日本語対応  2013-09-13
詳細文書だけでなく関数名やクラス名も日本語対応にする改良です
 全て ファイル ページ
Doxygen を利用する立場でのメモ

目次

Doxygen一般について

Windowsであってもコンソール出力はUTF-8

Windows であってもコンソールへの出力は UTF-8 になっています。設定変更を行っていない日本語版 Windows の cmd.exe から直接使おうとすると日本語部分が文字化けします。幸か不幸か進捗表示を日本語化する方法はまだないため、本作で可能になった出力ファイル名の日本語化の部分だけ問題となります。

Pythonへの対応はおまけっぽい?

Python への対応はどうにもおまけっぽいかも。日本語名関数を受け付けるようにしただけで詳しく検証してませんが。

GraphVizには日本語のフォント名を渡せない

GraphViz に渡すフォントの名前なんですが、Windows で ttf ファイルを指定する場合は日本語ではダメで、英語名を指定する必要があるみたいです。すべての ttf ファイルには日本語名(ローカル名)のほかに英語名が定義されているはずですのでそちらを利用してみてください。

Doxywizardについて

設定ファイルを読み出した時点では、基準となるパスが常にその設定ファイルの場所にリセットされてるような感じがするので注意。

過去の設定ファイル(Open Recent...)が随分あてにならないのはどうしてだろう?

本作独自の拡張について

\sk <ソートキー>

本作の doxygen 本体には \sk ソートキー というコマンドが追加されています(もちろん @sk でも可)。これはクラス名・関数名・ファイル名など名前の付けられるものに対して読み仮名を与える機能と思っていただいて構いません。これにより索引上の各項目は元の名前ではなくソートキーを基準に並べ替えられます。当然ながらオプション側で ALPHABETICAL_INDEXSORT_ で始まるものが有効になっていないと意味を持ちません。

並べ替え自体は依然 Unicode のコードポイント順で行われています。そのため、元の名前が片仮名だけであっても平仮名の読みを \sk で付け直していただく必要がありますし、長音符号は適切な母音に置き換える必要があります。ソートキーをつけなかった項目は漢字なら漢字のままで索引に出てきます。

完全に同一名の項目であれば、読み仮名はどれかに一回だけつけておけばすべてにたいして動作します。クラス同士の継承関係は不要です。逆に別の読みを与えることはできず、複数の別の読み仮名があった場合はどれか一つが採用されます。合成語に対して自動的に読み仮名を付けるような機能はありません。

ソートキーに文字種の制限は行われておらず、平仮名以外の文字も自由に指定できます。ただし文字種の一貫性を保たないと正常な索引を作ることができません。

使用例)

/*! \file 自動車.cpp

(※1)
*/

/*! \brief クラスの例 \sk じどうしゃ (※2)

*/
class 自動車
{
public:
    /*! \brief タイヤの数を与える構築子 (※3)
    
    \param タイヤの数 何輪で動いているかを整数で与えてください
    */
    自動車( int タイヤの数 ) : mタイヤの数( タイヤの数 ) { }
    
private:
    const int mタイヤの数; ///<! (※4)→ \sk たいやのかず
};
  1. ファイルに対する読み仮名は 自動車.cpp に対して \sk じどうしゃ.cpp と いうように末尾側の要素を合わせる必要はありますが、同様に同一名クラス・ 同一名関数での再指定は不要となります。 ここではクラスの方に定義しているのでファイルに対して \sk は用いていません。
  2. \sk の位置は \brief と同じ行でも構いませんし行を改めても構いません。
  3. 構築子はクラス名と同じなのでわざわざ \sk を再指定する必要はありません。
  4. 目的が索引なので読み仮名には m を付けない形も有りです。

LIMIT_FNAME_WITH_ASCII オプション

本作の doxygen には LIMIT_FNAME_WITH_ASCII というオプションが追加されています。doxywizard にも Expert→Project の 8番目あたりにあります。初期設定は NO になっており、これが互換動作になっています。ここを YES にすると、出力するファイル名にASCII外の文字(仮名文字や漢字含む)も使うようになります。NO のままだと当該ファイル名は UTF-8 を基礎にした _xhh_xhh_xhh といった感じの非常に長くて読みづらいファイル名を生成します。

日本語版 Wikipedia に見られるとおり、ファイル名にASCII外の文字を使った場合、その部分の URL を暗黙の裡に UTF-8 による %xx へ置き換える方法が広まっているので公開時の互換性に悩む必要はないでしょう。

なお、これとは別に一部のASCII内特殊文字を _数字 に置き換えてファイル名を作る部分は従来と変わりません。 またディレクトリに対して dir_英数字 が出力されることに関しても変化がありません。この英数字はディレクトリ文字列から作った MD5 ハッシュのようです。