DoxygenとXCodeのコメント機能のメモ
1行あけて記述すると詳細な説明のコメント部分になる、javadoc形式のautobriefを使うとコメントが描きやすい。
JAVADOC_AUTOBRIEF = YES
デフォルトだと、プライベートな実装までドキュメント化されてしまうので、ヘッダファイルだけコメント摘出したほうが良い。
FILE_PATTERNS = *.h
Xcodeでは、主な構文の前で、”command + option + /”のショートカットキーでコメントの雛形が挿入される。
例:class
雛形の挿入をサポートしている。
/**
クラスの概要
1行あけてから、クラスの主な機能をかく。
- 何の動作に責任を持つか？
- 実行時に協調するクラスはどれか？
*/
@interface DXWBAppDelegate : NSObject <NSApplicationDelegate>
@end
なお、ObjCでは”-“などのmarkDown構文はXCodeのQuickHelpではサポートされていない。doxygenだとサポートされている。
例:method
雛形の挿入をサポートしている。
/**
引数inRangeで示す文字列範囲の描画座標を矩形NSRectを返す
@param inRange 指定する文字列の範囲
@return 文字列の描画範囲
ここに詳細な説明を入れる。
*/
- (NSRect) rectForCharacterRange:(NSRange)inRange;
例:property
雛形の挿入をサポートしている。
/**
Textの描画領域とboundsの差の値
*/
@property (readonly) NSSize interSpacing;
空白行に続けて詳細は書ける。しかし、propertyに詳細な説明が必要な場合は設計が間違っている可能性があるので見直したほうが良い。
例:enum
雛形の挿入をサポートしていない。列挙体全体だけでなく、ここの値でも雛形の挿入はサポートされていない。
自前で、コメントをつける必要があるので、以下のコードを参考にする。 “/**”と”///”を使い分けると見た目がキレイになる。
/**
DXWBAppDelegateに関わるエラー定数。
ここに詳細な説明を入れる。
*/
enum E_DXWBAppDelegateError
{
/// 読み込みエラー
DXWBAppReadInapplicableDocumentTypeError,
/// 書き出しエラー
DXWBAppWriteInapplicableDocumentTypeError
};
例:文字列定数
雛形の挿入をサポートしていない。自前で、コメントをつける必要があるので、以下のコードを参考にする。
/**
NSString定数の宣言
*/
extern NSString* const DXWBAppConstString;
文字列定数に詳細な説明が必要な場合は設計が間違っている可能性があるので見直したほうが良い。
例:マクロ
雛形の挿入をサポートしていない。自前で、コメントをつける必要があるので、以下のコードを参考にする。
/**
NSApp.delegateへのアクセッサ
*/
#define AppDelegate ((DXWBAppDelegate *)[NSApp delegate])
文字列定数や列挙型をclassと同じグループにまとめる
Objective-Cでは、同じファイルで定義されている文字列定数や列挙型は、同じファイル中のクラスと強く関連づけられています。
それを明示するために、以下のように、”//@{“と”//@}”でくくるとDoxygenでグループ付けしてくれます。
//@{
// マクロ
.
.
// クラス定義
.
.
// 文字列定数
.
.
//@}