やまだです。……えーと、お忘れかもしれませんが、そういう奴もいるんです。
……えー、いるよな……たぶん……。
少なくとも、私は「いる」と信じたい！いーから、だまされたと思って「いる」としてみろ！だまされるから！……あれ？
……はぁ、まぁ、そんなものです。
今回も、しつこく Sandcastle の話です。ほとんど、困ったときの Sandcastle ネタ、って感じになってますが。
困ったもんだ。……あ、困ってるから Sandcastle ネタなのかｗ
で、.NET Framework で API リファレンスを作成する場合、ほとんど感覚的には JavaDoc 相当箇所に同様のコメントを入れていけば良いだけなのですが、ふと疑問に思うことがあるわけです。
「クラスとメソッドはその直前にXML形式でコメントを追加すれば良い。でも、名前空間に対するコメントはどこに書けば良いのよ？」
で、これまでの対処法としては、私は以下の２つでしのいでいたりしたわけなんですが。
その１．Sandcastle Help File Builder で ShowMissingNamespaces 指定を False にする
はい、へたれですね。名前空間にはコメント付いてなくても良しとしよー、と。
この指定を False にしておくと、作成される API リファレンスで「名前空間にコメント付いてないよー」というエラーが出力されなくなります。
名前空間に対するコメントなんて、さらりとなかったことにしてしまうというｗ
その２．Sandcastle Help File Builder で Namespaces メニューボタンから個別にコメントを追加する
まぁ、こーすれば名前空間に対するコメントは記述できます。
こんな画面が開くので、中段で対象とする名前空間を選んで、下段の「Edit the summary for the selected namespace」の中にコメントを書けば良いだけなんだけど……。
なんかねー、すっきりしないのよ。他のAPI仕様はソースコード内で、名前空間はツール内で、ってコメント場所が分かれると。
Javaなんかだと、package.html ファイルをパッケージごとに作っておけるので、ソースコードとコメントがまとめて管理できるので便利なんだけどなー、とか思ったりします。
それに、<summary> タグはいいけど <remarks> タグはどうするのよ、ってな話もあったりします。
タグごと書けば、両方書けるんだけどねー。でも、生成されるファイルではどちらも <summary> タグの位置だから変なのよ。やっぱり、<summary> の内容は冒頭に、<remarks> の内容は末尾に出力して欲しいよねー、と。
ところが、この２つ以外にも方法があるってことが、ようやく最近になってわかってきたりして。
それが次に挙げる「その３」、とゆーわけです。
その３．名前空間ごとに NamespaceDoc クラスを作成する。
ということで、この方法があったりします。
つまり、名前空間のコメントを入れるためのクラスを定義してしまうってゆー、まーなんというか、盲点というか、抜け道というかｗ
C# だとこんな感じですねー。
namespace 対象とする名前空間 {
/// <summary>
/// 名前空間の概要
/// </summary>
/// <remarks>名前空間の補足</remarks>
[System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
class NamespaceDoc {
}
}
VB.NET だとこんな感じですねー。VB.NET だと明示的に名前空間を書かないのが通常かもしれないですが、このクラスについては明示的に書いておいた方が混乱がないかもです。
Namespace 対象とする名前空間
''' <summary>
''' 名前空間の概要
''' </summary>
''' <remarks>名前空間の補足</remarks>
<System.Runtime.CompilerServices.CompilerGeneratedAttribute()> _
Public Class NamespaceDoc
End Class
End Namespace
で、これらのクラスを定義しておくと、Sandcastle でちゃんと名前空間用のコメントが反映されることとなりますー。
あ、この方法は「その２」とは共存できないようなので注意です。まぁ、当然っちゃ当然のような気もするけど。定義が重複している、とかってエラーが表示されたような……。
↑ここで再検証しないところが、またへたれですね。＃もー、そんな気力はとっくになくなっているので。
で、この方法をどこで見つけたかというとですね。えーと、さっきの「その２」で挙げたウィンドウ右下のところに「Help」ってボタンがあるですよ。
ツールの操作方法なんて直感的にわかるし、英語読むなんて面倒だしなぁ、……と放置だったんですが、ある時、なんとなく「Help」ボタンを押して、ヘルプファイルをざっと眺めてみて、……あれ？この「Using a NamespaceDoc Class」って何だ？と思ったという（苦笑）。
やっぱ、ドキュメント読むって大事だわ（笑）。
で、ドキュメントを読むことも大事だけど、空気を読むことも大事ですね、という話でした。……あれ？
えーと、……KY でごめんなさい、ごめんなさい、ごめんなさい。
内容のわりに長いエントリでごめんなさい、ごめんなさい、ごめんなさい。
それでは皆様、良いお年を。また、１月末にお会いしましょう。
……をい。 ← でも、しゃれになってなかったりする…… orz