doxygen コメントの @file に関して

[m-tmatma]

doxygen コメントで @file があるファイルとないファイルがあります。
@file がないとたぶん doxygen は解析対象にしてくれないはず。

checkEncoding.py で文字コードをチェックして、ソースやリソースが UTF-8 でない と
ビルドを失敗させるようにしています。

すべてのソースファイルに @file をつけた上で、同様に @file がないソースがあると
ビルドを失敗させるようにしようと思います。

どう思いますか?

[beru]

@file くらいであれば良いと思います。

ただDoxygen用の関数コメントを書くのは億劫なので、関数コメントの記述までは必須になって欲しくないなぁと思います。

[m-tmatma]

ただDoxygen用の関数コメントを書くのは億劫なので、関数コメントの記述までは必須になって欲しくないなぁと思います。

@file だけです。

[berryzplus]

@file だけです。

@file だけ、かつ、従来通り「記述内容を問わない」であれば問題ないと思います。
「とりあえず @file を付ける」のあとにくる
「適切な内容に書き換える」の工程がめんどくさそうですが 😄

[berryzplus]

#535 ってこれのPRですか？
手作業をルール化するなら、現状横並びのテキトー運用で勘弁してほしいです。
上に書いてたコメントはそういう流れの中でのコメントです。

ツール作って対処します。
だと手作業のルール化と話が変わってくると思います。

あるべき姿（＝仕様）を定義して、
仕様通りになるようなツールを作る話になると思います。

ツール作って対応するなら @file 相対パス を埋め込みたいです。
https://qiita.com/inabe49/items/23e615649e8539d857a8

doxygenの出力って、@fileタグとかをキーに出力するものなので、
タグのコンテンツがないのはまずい気がします。

@file の空タグを入れるpython関数は、入れるべき相対パスを知ってるように見えます。
持ってる情報を整形して一緒に吐き出したらいい気がします。

空タグを入れるかどうか判定する前段階の処理で、
既存コードに @fileタグ が含まれているか判定しているように見えます。
せっかくツール化するのなら、一律の基準に沿っているか合わせてチェックしてはどうでしょう。

doxygen記述ルール（ツール仕様）案
@file 相対パス(+行末記号)
例) @file sakura_core/_os/CClipboard.cpp
・ファイル内に現れる最初の@fileについての定義
・2つ目以降の@fileについてはツールは無視する（手作業で削除する）

いろいろやり出すと面倒なので「仕様化は @file のみ」は変えない方向で。

[m-tmatma]

ツール作って対応するなら @file 相対パス を埋め込みたいです。

既存のソースで @file のパスが書かれていないものが、
あったので直した方がいいのかと思ったのですが、

https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdfile
を見ると、ファイル名はオプションのようです。

同じファイル名のファイルが複数ある場合に指定したらいいみたいです。
別に必須でないのなら、入れなくともいいと考えました。

ただスクリプト的には相対パスを入れるのは対応可能です。

[berryzplus]

別に必須でないのなら、入れなくともいいと考えました。

理解。

doxygen自体もパス見て解析するんだから「省略可能」なのは納得しました。

で、どうするか・・・
ちょっと考えさせてください。

[m-tmatma]

ただスクリプト的には相対パスを入れるのは対応可能です。

試しにやり始めてみたら、思いの外大変だった。
@file 以降のファイル名の解析の部分がめんどくさい。
ちょっと保留。

[m-tmatma]

↑ 新たに @file を足す場合は簡単なんだけど、すでに @file 以降の部分のファイル名、パス名を
解析して、かつ末尾が */ のコメント終端で終わる場合があるので、ファイルパスとして
どんな文字があり得るか考えた上で解析する必要がある。

あと、今回 @file の部分がない場合に追加する対応をしたが、
doxygen を正しく動作させるためには @file 以降のパスが実際のパスと
異なっている場合のパスを適切に直すという対応も必要。

単純に以下のようにしたら対応は簡単

/*	@file	*/	処理
○	○	○	/*! @file */ に置き換える
○	○	×	/*! @file に置き換える
×	○	○	@file */ に置き換える
×	○	×	@file に置き換える

○ は入力に含む場合、×は入力に含まない場合

[berryzplus]

で、どうするか・・・
ちょっと考えさせてください。

相対パス要らない、で良さそうです。

他にもあった懸念点。

• StdAfx.cppの @file をどうするか（PCHを生成するためのダミーなので中身がない）
• 自動生成ファイルの @file をどうするか（付けといたほうがいいはず）

StdAfx.cppについては、特定のファイルを除外にできる仕掛けができれば解決できそうです。
こういうファイルは他にないのであえて対策しなくてもよいかもです。

自動生成ファイルは Funccode_enum.h のことを言ってます。
仕組み分かっとらんのですが @file が付いているファイルから
なんとなく定義を拾ってドキュメント化してくれるものと理解しております。

Funccode_enum.h にはコメントがないのでたぶん対象外になると思います。
でもこれコマンド識別子なので名前だけでもドキュメント化されて欲しいです。

現状でどういうドキュメントが吐かれるか見たいです。
しかしJava環境だとEclipseが勝手にやってくれるから
ぶっちゃけdoxygenの使い方知らんとか・・・ 😢

[berryzplus]

単純に以下のようにしたら対応は簡単

正規表現で s|(/\*)?.*(@file)\b.*(\*/)?|$1 $2 $3| ってことですかね？
　　　　　　↑行末空白の扱いがビミョー・・・。

[m-tmatma]

自動生成ファイルは Funccode_enum.h のことを言ってます。
仕組み分かっとらんのですが @file が付いているファイルから
なんとなく定義を拾ってドキュメント化してくれるものと理解しております。

Funccode_enum.h にはコメントがないのでたぶん対象外になると思います。
でもこれコマンド識別子なので名前だけでもドキュメント化されて欲しいです。

自動生成ファイルは git には登録しないので、自動生成プログラム側での対応が必要です。
追加するのはいいですが、別枠での対応が必要です。

[m-tmatma]

正規表現で s|(/\*)?.*(@file)\b.*(\*/)?|$1 $2 $3| ってことですかね？
　　　　　　↑行末空白の扱いがビミョー・・・。

@file と /* と */ のいずれかしかないという割り切りをする前提ではあります。

[m-tmatma]

#535 はマージしました。
自動生成のファイルの検討はまだ

[m-tmatma]

#535 はマージしました。
自動生成のファイルの検討はまだ

#564 で対応済み