Sandcastle

Sandcastle Help File Builder 1.8.0.3 が出ています

やまだ — Sun, 31 Jan 2010 21:03:00 GMT

……やまだです。……ええ、やまだです。

Sandcastle Help File Builder (SHFB) 1.8.0.3 がでてますね。いやー、長いままβだったのでこのまま正式版がでないのかと思ってましたが。

そういえば、Sandcastle 本体の方はここ１年以上更新されていないようです……。

仕事の内容が変わったこともあって、最近は .NET のドキュメントを作る必要もなくなってたりしますが、ちょっと懐かしくなって触ってみようかと。

で、触ってみた印象です。

【変わらないように見えるところ】

・あまりスペックが高くないPCで実行しようとしたり、もしくは他のアプリケーションを多数起動していると、メモリ不足などが発生しやすい。

　で、他のアプリ一通り終了してから再実行しなければならなかったり、延々処理が止まっているように見えたり、と。（まぁ、しかたがないことかもしれませんが。）

【悪くなったように見えるところ】

・設定可能な項目が増えたように思います。自由度が上がった、という意味では良いことなのでしょうが、何を、どこまで設定してよいのか、わかりにくくなった気がします。

・で、GUIが変わってるので、どこで対象アセンブリとXMLを指定してよいか、なかなか分かりませんでした。それがなきゃ始まらんだろうとｗ

　↑ProjectExplorer 上で右クリックメニューから追加だ！、ということを理解するまで小一時間……。

・SHFB の設定ファイルの書式(拡張子)が変わって、以前の設定ファイルを解釈してくれなくなっています。

↑変換メニューはあるけど、途中でエラーになりました。設定ファイルを新たに作り直してから、テキストベースで見比べて手作業更新が一番早そうな気もします。

【良くなったと思えるところ】

・Sandcastle 側のエラーをちゃんと拾ってエラーコード付きで出力してくれるようになったようです。

　↑最大の改善点？エラーコードごとの対策は、ヘルプファイルの Errors and Warningd を参照すべし。

・安定性が上がった？

　↑……かも？

え、と、あと次の設定は False にしておくのが個人的には推奨です。

DocumentInheritedFrameworkMembers

フレームワークから継承するメソッドのコメントまで探しにいくみたいなので、環境によってはかなりシャレにならない負荷が……。

Sandcastle Style の方も更新されているようなので、この辺にこっそり日本語化ファイルの更新版も置いておきますね。

では。

ドキュメントは読みましょう？（しつこく Sandcastle ）

やまだ — Wed, 24 Dec 2008 23:18:00 GMT

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

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

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

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

今回も、しつこく 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

WPFでSandcastleを使ってみた

やまだ — Sun, 30 Nov 2008 20:15:00 GMT

えーと、前回の大阪勉強会以来ですかね。とりあえず11月の駆け込みエントリということでｗ

やまだです。

なんか大阪の方が私のホームになってきた感のある今日この頃、皆様いかがお過ごしでしょうか？

＃ホームレス、という話もありますがｗ

相変わらずちまちまと自宅でWPFプログラムを弄ってたりします。あまり時間もとれないし、一つ機能を入れるたびにリファクタリングの嵐で遅々としてしか進んでいなかったりしますが。

で、せっかくWPFでプログラム作ってることだし、ひさしぶりにSandcastleでAPIリファレンスでも出してみるかなぁ、と。別にWPFだからってSandcastleの何が変わるわけでもないはずで、まぁとりあえずやってみるべしと。

で、それだけのことなのに、なぜかはまること、はまること。

その１．なんか変だ

え、変なのはお前だ、って？あ、はい、まあそれは置いておくとして（認めるのかっ）

生成されたAPIリファレンスの表示が何かおかしかったりします。ドキュメント内リンクも有効になっていないし。

でも、"Build completed successfully." って表示が出てるしなぁ。ちゃんと出力されているはずなんだが……、とログを見て、途中にある文字列に気づきます。

OutOfMemory

……おーい。……ぉーぃ、ぉーぃ、ぉーぃ……。

むなしくコダマが響きます……。

……成功していないだろうがっ！

教訓１．Sandcastle Help File Builder は、成功していなくても "Build completed successfully." って表示することがあるので要注意です。何かあやしいと思ったらログを追っかけるべし！

その２．さっきは成功したのに……

え、学習効果がないのは、お前だ、って？……あー、そーかも。

なんかねー、ドキュメントの再生成を繰り返しているうちに、動作が変わるんですよ。で、原因は↑の OutOfMemory だったりして。

で、一度終了させて、もう一度起動しなおすと今度はちゃんと動いたり。

……これって、メモリリーク起こしてないか？とあらぬ疑いをかけてみる。

＃自分の期待どおりの動作しなかったら、バグだーと叫ぶ困った人、いますよねー。……はっ、私かっ！？

教訓２．Sandcastle Help File Builder が期待通りの動作をしなかった場合には、一度再起動してみましょう。今度はちゃんと動くかもよ？

その３．お前は何をしてるんだっ！？

え、意味不明なのは(以下略)。……はいはい、どーせそうですよー。

XAML では明示的にクラス定義はしないですよね。だから、".xaml.cs", ".xaml.vb" 側の partial class 側に<sammary>タグでコメントを書いています。

自分では、このやり方で問題ないように思っていたんですが、生成されたドキュメントでクラス名の一覧を見てみると、クラス名がコメントに表示されている……。おーい、自分で記述した方のコメントはどこに行ったんだー？

……と思って、クラスの方のAPIを見てみると、確かに自分が書いたコメントはありましたけど、その他にそのクラス名だけのコメントが１行追加されている……。何だコレ？

で、XAML定義をミスってIDEがエラー吐いたとき、その原因を追っかけてってわかったですよ。XAMLから生成されたC#(VB)のコードに勝手に<sammary>タグが追加されてるっ！

意味のない情報を自動生成すんなー……。

教訓３．XAMLで定義したクラスには、Visual Studioによりクラス名だけの<sammary>タグがつけられたりします。まぁ、そーゆーものなので、気にするのはやめましょう。

では、次回はまた大晦日にお会いしましょう？

帰ってきた Sandcastle

やまだ — Tue, 17 Jun 2008 01:57:00 GMT

えー……ま、いいか。

やまだです。

6/28(土) は大阪勉強会#20です。なんだかんだで話題に上がっているわりには、まだまだ空きはありそうです。

というわけで。

みんな来ない？僕は行くよー（ＴーＴ）

とか書いておきながら、私は別件のため懇親会は欠席の予定だったりしますが。

＃というか、そもそもその別件のためにこの日に大阪行きだったわけで。

で、今週末の東京勉強会#21の方まで行く体力と気力が残るだろうか……。

で、前回「Sandcastleはどこに行った？」的なエントリを書いてしまったわけなので、一応その後始末をしておこうと。

Sandcastle Help File Builder のページにいくと、Sandcastle へのリンクが張りなおされていました。

> Download the Sandcastle January 2008 release from the Microsoft Download Center

とありますね。ですが、これ、リンク先を確かめてみると実際には、May 2008 Release でした。ですので、Sandcastle の最新版が上記からダウンロードできるようです。

ということで、Microsoft の Download Center に舞い戻った、とのお話でした。

では、Sandcastle関連のリンク集を整理、ということで。

・Sandcastle May 2008 Release (v2.4.10520)

ヘルプファイル作成ツールのエンジン

・Sandcastle Help File Builder 1.7.0.0 Production

ヘルプファイル作成のGUIツール

・Sandcastle Style

以前、Presentation Style Patch と呼んでいたもの

以上でっす。

Sandcastle が消えている？

やまだ — Thu, 12 Jun 2008 02:18:00 GMT

やまだです。

こんな私ですが「書き込みを楽しみにしてるよ」という方がいらっしゃいました。ありがたいことです。

「いつも書き込みないかってチェックしてるんだけどさー」　エントリ書けてなくてますます申し訳ない……。

「画伯のエントリを」　……をい。

それ、果てしなく違いますから！何かが根本的に間違ってますから！

何が間違ってるかは内緒っ！……いや、そうじゃなくて。

ま、そーゆーどーでもよい人ことは置いときまして。

ちょっと前にこっちに書いたのですが、Sandcastle 関係のもろもろがリリースされました。

> ・Sandcastle May 2008 Release (v2.4.10520)

え、何、このリンク先……「プロジェクトはまだできてません(意訳)」って。確かにあったんですよ前は。

なんで公開直後にプロジェクト自体が消えているの？

Sandcastle がないと、Sandcastle Help File Builder だけあっても意味がないぞ。

逆なら、まだ DocProject for Sandcastle とかでなんとかなるのかもしれないけどさ。

＃でも DocProject 自体がどんなものかまだよくわかってない。わかったら教えれ < 他力本願

Sandcastle の行き先なのですが……、Builder の方のページでの関連リソースが↓みたいな感じになっちゃってます。

> Download the Sandcastle January 2008 release from (-- New site pending --).

とにかく、今はサイト自体が閉じちゃってる or 移転中みたいですね。

＃私はダウンロードしちゃってるので、ライセンスさえ問題なければ再配布してもよいけどさっ。

頼むから、ここまで来て公開停止になるって展開だけはかんべんしてくれよ～。

Sandcastle がどこに行っちゃったのか、お心当たりのある方はご一報を。（お礼は何もできないけどさっ）

では。

Sandcastle もろもろリリース

やまだ — Thu, 05 Jun 2008 03:23:00 GMT

えー、やまだです。

少し前、自分のブログを見に行ったら、ココロがお風呂に入っているところでした。ココロの秘密日記を開いたところ、「みちゃだめですよ！」といわれました。なんだかこの符合に感心してよいのか、とりあえず反省すべきなのか、そこが悩みどころです。

本格的に名前を変えようかと思いつつ、まだまだやまだです。

えー、片桐さんちのエントリでも書かれていますが、Sandcastle関連もろもろのリリースです。

・Sandcastle May 2008 Release (v2.4.10520)

.NET Framework のヘルプファイル作成エンジンですね。今回からバージョン番号も併記になったようです。

えーと変更内容は……各自でお確かめください(笑)。

【追記】「前回の」 Presentation Patch の内容が「ほとんど」取り込まれているようです。

~~でも、配布ファイルサイズがいきなり５割増しになっているのでかなり大規模改造だったのではないかと。~~

【追記】ごめんなさい。嘘です。サイズ５割増しは、Builderの方でした。

・Sandcastle Help File Builder 1.7.0.0 Production

ヘルプファイル作成のGUIツールですね。実質、これ込みで Sandcastle と呼んで良いような……。

いちいちコマンドラインから起動スクリプトの入力なんてしてられませんしねぇ。

変更内容は……片桐さんちでチェックだ！(笑)。

・Sandcastle Style

以前、Presentation Style Patch と呼んでいたもの。~~こちらは数日の後にリリース予定となってますが。~~

【追記】このエントリ書いたその日のうちに、公開されたみたいですね。

だから Patch なら最初からあてときゃよいようなものですが、何か妙なしがらみでもあるのかしら。

変更内容は……~~公開前に~~わかるわけなかろーに(笑)。

で、最新版対応の日本語化ファイルなんですが、(以下コメントに続く……)

Sandcastle January 2008 がリリースされています。

やまだ — Thu, 24 Jan 2008 03:36:00 GMT

片桐さんのところでもアナウンスされていますが、Sandcastle Help File Builder 1.6.0.4 がリリースされています。

入手はこちらから。

で、その対象となる Sandcastle ですが、October 2007 Community Technology Preview (CTP) から一向に更新されている様子がないんですよね。どうしたもんかと思ってると、以下に最新版がありました。

Sandcastle January 2008
http://www.codeplex.com/Sandcastle

＃お、Sandcastle まで CodePlex にお引越しですね。

あと、正式リリースになりました。CTP がなくなってます！……と書きたいところなんですが、インストールすると Pre-Release Lisence とかって文字がしっかりとあるんですよねぇ。引っ越しにあたって、 CTP 表記を取りこぼした、とかだったりして？

中身を確認したところでは、旧バージョンに比べて大きな変更はなさそうですね。とりあえず、さくっと旧バージョンの時につくった日本語化ファイルを更新して動かしてみたところ特に問題はなさそうです。

コードから見るに、今回は VS2005 形式で出力した場合のフィードバック出力がちょっとまともになったっぽいですね。SHFB からフィードバック出力の有無がちゃんと指定どおりに制御できているようだし。前回は無条件に生成されていた気が……。

ただ、フィードバック時のメール表題が化けまくりになるんだが……ううむ。

Sandcastle Help File Builder 1.6.0.4 がリリースされます。

やまだ — Fri, 18 Jan 2008 01:40:00 GMT

とは言っても、まだ出てはいなかったりします。ですので「されました」ではありません。

えーと、ご存じない方のために再度書いておくと、Sandcastle ってのは .NET で API リファレンスを作成できるツールです。.NET 版 Javadoc っていうと一番簡単かなぁ？Sandacastle Help File Builder　はそれを GUI　から操作するためのツールってことになります。＃使い回し使い回し(^^;

で、Sandcastle Help File Builder のページ　によると、1/22 までに　1.6.0.4 をリリースするよって予告でした。

まあ予告だけなら今までもあったのですが、そこに "support for the Sandcastle January 2008 CTP" との記述がありました。ということは、それまでに Sandcastle も新版がリリースされるということですね。

ここ２ヶ月ばかりリリースが止まっていたので、まだ改善されていることだけでも単純にうれしいですね。ただ、何をどこまで改善されているか、が問題なんですが。正直、Javadoc の域からはまだ遠いし……。

＃ま、Javadocとは目指すところが違うといわれればそれまでですが。

あー、ほそぼそと Sandcastle の日本語化とかも進めてたりしますが、欲しい人とかいます？

Sandcastle Help File Builder 1.6.0.1 がリリースされています。

やまだ — Thu, 01 Nov 2007 22:50:00 GMT

「あー、Sandcastle がアップデートしてるぅ。これはインストールしとかないとなぁ」と思って即座に入れてみたはよいものの、
「ぬおー、Builder が動かないー。これでどうしろっちゅうんじゃー！」とかでパニックになってしまったあわて者(……いるのか？)に朗報です。

Sandcastle Help File Builder が 1.6.0.1 にアップデートされましたー。入手はこちらから。
やはり、Sandcastle と Help File Builder は一組でインストールした方がよいですね。

で、先日公開された新しい Sandcastle にも日本語は組み込まれておりません。てっとり早く、日本語対応をしてみたい方は前回のエントリをどぞ。

……私の方は、とある事情で環境を Fix せざるを得ない状況なので、新バージョンでの確認はできておりません。やってみた方がいれば、ご報告をいただければありがたいです。

ではでは。

【補足追記】あー、ご存知ない方のために。Sandcastle ってのは .NET で API リファレンスを作成できるツールです。.NET 版 Javadoc っていうと一番簡単かな？
で、Sandacastle Help File Builder　はそれを GUI　から操作するためのツールってことになります。

Sandcastle 日本語化 Revised

やまだ — Wed, 31 Oct 2007 02:54:00 GMT

＃いやー、予想より若干CTPがでるの早かった……。

Sandcastle - October 2007 Community Technology Preview (CTP)

がリリースされました。バージョンとしては 2.3.8000.26 になりますね。入手はここから。

でも、Sandcastle Help File Builder が未対応（近日中に公開予定）なので、その公開までインストールは待った方がよいかもしれません。

で、これだけだと、ひろえむさんや片桐さんのエントリに加えて、付加情報がまったくない！ので、

ここで作った日本語対応ファイルを新版に対応させてみました。興味ある方はこちらから。

＃まぁ、あまり代わり映えしませんが。

使い方は過去のエントリをさかのぼっていってくださいな（手抜き）。

ご使用は自己責任で、ということでお願いします。

＃Sandcastle Help File Builder より先に出したぞ、と。