いや、まだだから

やまだの仮想庭園 ~ いつか実体の伴う日まで

目次

Blog 利用状況

記事カテゴリ

書庫

日記カテゴリ

リンク

ドキュメントは読みましょう?(しつこく Sandcastle )

やまだです。……えーと、お忘れかもしれませんが、そういう奴もいるんです。

……えー、いるよな……たぶん……。

少なくとも、私は「いる」と信じたい!いーから、だまされたと思って「いる」としてみろ!だまされるから!……あれ?

……はぁ、まぁ、そんなものです。

 

今回も、しつこく Sandcastle の話です。ほとんど、困ったときの Sandcastle ネタ、って感じになってますが。

困ったもんだ。……あ、困ってるから Sandcastle ネタなのかw

 

で、.NET Framework で API リファレンスを作成する場合、ほとんど感覚的には JavaDoc 相当箇所に同様のコメントを入れていけば良いだけなのですが、ふと疑問に思うことがあるわけです。

「クラスとメソッドはその直前にXML形式でコメントを追加すれば良い。でも、名前空間に対するコメントはどこに書けば良いのよ?」

で、これまでの対処法としては、私は以下の2つでしのいでいたりしたわけなんですが。


その1.Sandcastle Help File Builder で ShowMissingNamespaces 指定を False にする

はい、へたれですね。名前空間にはコメント付いてなくても良しとしよー、と。

この指定を False にしておくと、作成される API リファレンスで「名前空間にコメント付いてないよー」というエラーが出力されなくなります。

名前空間に対するコメントなんて、さらりとなかったことにしてしまうというw


その2.Sandcastle Help File Builder で Namespaces メニューボタンから個別にコメントを追加する

まぁ、こーすれば名前空間に対するコメントは記述できます。

image

こんな画面が開くので、中段で対象とする名前空間を選んで、下段の「Edit the summary for the selected namespace」の中にコメントを書けば良いだけなんだけど……。

なんかねー、すっきりしないのよ。他のAPI仕様はソースコード内で、名前空間はツール内で、ってコメント場所が分かれると。

Javaなんかだと、package.html ファイルをパッケージごとに作っておけるので、ソースコードとコメントがまとめて管理できるので便利なんだけどなー、とか思ったりします。

それに、<summary> タグはいいけど <remarks> タグはどうするのよ、ってな話もあったりします。

タグごと書けば、両方書けるんだけどねー。でも、生成されるファイルではどちらも <summary> タグの位置だから変なのよ。やっぱり、<summary> の内容は冒頭に、<remarks> の内容は末尾に出力して欲しいよねー、と。


ところが、この2つ以外にも方法があるってことが、ようやく最近になってわかってきたりして。

それが次に挙げる「その3」、とゆーわけです。


その3.名前空間ごとに NamespaceDoc クラスを作成する。

ということで、この方法があったりします。

つまり、名前空間のコメントを入れるためのクラスを定義してしまうってゆー、まーなんというか、盲点というか、抜け道というかw

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 でちゃんと名前空間用のコメントが反映されることとなりますー。

あ、この方法は「その2」とは共存できないようなので注意です。まぁ、当然っちゃ当然のような気もするけど。定義が重複している、とかってエラーが表示されたような……。

↑ここで再検証しないところが、またへたれですね。#もー、そんな気力はとっくになくなっているので。

で、この方法をどこで見つけたかというとですね。えーと、さっきの「その2」で挙げたウィンドウ右下のところに「Help」ってボタンがあるですよ。

ツールの操作方法なんて直感的にわかるし、英語読むなんて面倒だしなぁ、……と放置だったんですが、ある時、なんとなく「Help」ボタンを押して、ヘルプファイルをざっと眺めてみて、……あれ?この「Using a NamespaceDoc Class」って何だ?と思ったという(苦笑)。

やっぱ、ドキュメント読むって大事だわ(笑)。


で、ドキュメントを読むことも大事だけど、空気を読むことも大事ですね、という話でした。……あれ?

えーと、……KY でごめんなさい、ごめんなさい、ごめんなさい。

内容のわりに長いエントリでごめんなさい、ごめんなさい、ごめんなさい。

 

それでは皆様、良いお年を。また、1月末にお会いしましょう。

……をい。 ← でも、しゃれになってなかったりする…… orz

投稿日時 : 2008年12月24日 23:18

Feedback

# [.NET] SandCastle 用に、 namespace へのコメントをソースコードに埋め込む方法 2008/12/26 12:45 biac の それさえもおそらくは幸せな日々@nifty

「いや、まだだから」 より。 その3.名前空間ごとに NamespaceDoc クラスを作成する。 ということで、この方法があったりします。つまり、名前空間のコメントを入れるためのクラスを定義してしまうってゆー、まーなんというか、盲点というか、抜け道というかw C# だとこんな感じですねー。 namespace 対象と

# re: ドキュメントは読みましょう?(しつこく Sandcastle ) 2008/12/26 19:45 やまだ

biac さん、トラックバックどうもです。

> はい、 まさにドキュメント読んでませんでした orz
ですよね?やっぱり読んでなかったりしますよね?
↑こらこら、そこで安心してどーする。

> ともあれ、 これで楽になるぞ (^^;
お役に立てたようで何よりですー。

> ただ、 このやり方だと、 不要なクラスがバイナリに入っちゃうのがちょっちいやんな感じ。
さすが、そこで終わらないのが biac さんですねぇ。
#私は、ゴミがまじりそうだな、とは思いましたけど、ま、できるからいーや、誤差誤差ーと(^^,

タイトル  
名前  
Url
コメント