C# と VB.NET の質問掲示板

ASP.NET、C++/CLI、Java 何でもどうぞ

C# と VB.NET の入門サイト

Re[6]: 最近のC#のドキュメントの作り方

(過去ログ 96 を表示中)

[トピック内 11 記事 (1 - 11 表示)]　 << 0 >>

■57388 / inTopicNo.1)

　最近のC#のドキュメントの作り方

▼■

□投稿者/ めめ (16回)-(2011/02/24(Thu) 17:32:52)

分類:[C#]　

2011/02/24(Thu) 17:34:46 編集(投稿者)
2011/02/24(Thu) 17:33:45 編集(投稿者)

コメントの書き方、書いたコメントのドキュメント化について質問です。

JavaではJavaDocという有名で簡単なドキュメントの作り方があると思います。
FlexなどのActionScriptの場合はASDocというJavaDocもどきを簡単に作成することができます。
“最近”のC#のコメントは、この辺りはどのようになっているのでしょうか？
（最近、ASDocなどはバージョンが上がり、サポートファイルが増えるなどの変化もありましたので）

自分なりに調べてみた所、XMLドキュメントを書くのが基本なのかなと感じました。（参考１）
しかし、これ単体ではただのXMLファイルであるだけで、分かりやすいドキュメントにはなりそうにありません。
他言語が基本フリーでドキュメントができるのもあって、C#でもフリーでよく使われるものを探しています。
（古いVisualStudioではドキュメント化できるような記述もありましたが、現在はありませんでした。（参考２））
（また、参考１ではサンドキャッスルというツールが挙げられていました）

探した記事が少し古めというのもあって、今現在、なにが主流の手法になっているのか確信を持てないでいます。
.Net4と合わせて、VisualStudioでもツールをダウンロードできるようになっているのもあって、
いろいろ変化していそうですし、そっちでツールを決めることもできそうという懸念もあります。

なにか小ネタでも構いません。この辺り分かる方いましたら、返信頂けると助かります。
よろしくお願いします。

環境
Windows7 Professional x64
VisualStudio 2010 Professional

参考
１　http://msdn.microsoft.com/ja-jp/library/b2s063f7
２　http://www.atmarkit.co.jp/fdotnet/teamdev/teamdev02/teamdev02_01.html

引用返信 編集キー/

■57397 / inTopicNo.2)

　Re[1]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ やじゅ (1844回)-(2011/02/24(Thu) 21:46:47)

■No57388 (めめさん) に返信

やはり、フリーだと Sandcastle くらいなんじゃないかな。
http://d.hatena.ne.jp/aoki1210/20110108
http://d.hatena.ne.jp/Csh/20100315/1268663023

支援ツールとして、XMLドキュメントコメントの雛型生成アドイン
GhostDoc http://submain.com/products/ghostdoc.aspx
Atomineer Utils Pro Documentation
http://visualstudiogallery.msdn.microsoft.com/7912CCF4-60B8-4132-BACE-5ACACEB7233B/

引用返信 編集キー/

■57402 / inTopicNo.3)

　Re[2]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ めめ (17回)-(2011/02/25(Fri) 10:30:37)

>>やじゅさんに返信

Sandcastleについて、もう少し調べてみた…というか作成してみました。

ドキュメントの出来自体は十分かと思うのですが、それ単体では実行することが叶いませんでした。
しかたなく、SandcastleHelpFileBuilderの力を借りて書き出しています。

ただ、これだとVisualStudioで完結していません。

わざわざ別のツールを立ち上げるのが、手間というか情けなく感じてしまいます。
Eclipseではアドインの強みもあるのでしょうが、フリーのツールで容易くできることが、
なぜVisualStudioでは未だにこれほど手間が必要になるのか、とても不思議です。

VisualStudioだけで、ドキュメント化は完結できないのでしょうか？

引用返信 編集キー/

■57415 / inTopicNo.4)

　Re[3]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ ＰＡＴＩＯ (83回)-(2011/02/25(Fri) 14:02:37)

■No57402 (めめさん) に返信
> ただ、これだとVisualStudioで完結していません。
>
> わざわざ別のツールを立ち上げるのが、手間というか情けなく感じてしまいます。
> Eclipseではアドインの強みもあるのでしょうが、フリーのツールで容易くできることが、
> なぜVisualStudioでは未だにこれほど手間が必要になるのか、とても不思議です。
>
> VisualStudioだけで、ドキュメント化は完結できないのでしょうか？

私が知らないだけかもしれませんが、VisualStudioの環境でソースからドキュメントを
起こすという方向でのアプローチは見た事がありません。
RADツール系の物は見た事があると思いますが、おそらく言われている物とは
別の物だと思うので参考になりませんよね。

私の場合、C#ではなくてC++なのでdoxygenを使っていますが、
それに関して特に不満はありません。
私の場合、ソースからドキュメントを起こすのではなくて
設計書を作成してコーディングするというスタイルなので
ソースを記述する時は基本的に設計書がある事が前提になっています。
そんなこんなでその方向のアプローチを必要としていないからです。

引用返信 編集キー/

■57425 / inTopicNo.5)

　Re[3]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ aetos (356回)-(2011/02/25(Fri) 17:06:11)

■No57402 (めめさん) に返信
> VisualStudioだけで、ドキュメント化は完結できないのでしょうか？

「Support for full Visual Studio integration is planned for a future release. 」だそうです。

http://shfb.codeplex.com/

*.shfbproj ファイルは MSBuild でビルドできますから、一度 GUI でプロジェクトファイルを作った後は、VS のビルドイベントに登録しておけば自動化できます（ビルド時間はかなり伸びますが）。
ただ、ソリューションのビルドをすべて終えた後のアクションというのはありませんので、ソリューション内でのプロジェクト依存関係で最後にビルドされるプロジェクトのビルドイベントに仕込む必要があるでしょう。

引用返信 編集キー/

■57480 / inTopicNo.6)

　Re[4]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ めめ (18回)-(2011/03/01(Tue) 10:25:45)

ＰＡＴＩＯさん
>私の場合、C#ではなくてC++なのでdoxygenを使っていますが、それに関して特に不満はありません。
>私の場合、ソースからドキュメントを起こすのではなくて
>設計書を作成してコーディングするというスタイルなので
>ソースを記述する時は基本的に設計書がある事が前提になっています。
>そんなこんなでその方向のアプローチを必要としていないからです。

なるほど。私的にはありなのかもしれません。
しかし、私は仕様書とプログラムのドキュメントは根本的に用途は別だと思います。
確かに、ソースを記述する時にドキュメントが必要であることはないですが、成果物として残すと残さないのでは、だいぶ違うと思います。
特にライブラリ系を作りだすと、関数のリファレンスは絶対に必要だと思います。
あまり使わないのでどのクラスだったか覚えていない。ソースで探す、あるいは作り直す。なんていうのはちょっと情けないかなぁ、と。

Ｃ＃は好きな言語だし、アンチする意図はなかったのですが、
まさかそういった機能を未だに標準で備えていないのは驚きでした。

■No57425 (aetos さん) に返信
>>VisualStudioだけで、ドキュメント化は完結できないのでしょうか？
> 「Support for full Visual Studio integration is planned for a future release. 」だそうです。

なるほど、今後サポートされる可能性はあるかもしれないのですね。

> http://shfb.codeplex.com/
> *.shfbproj ファイルは MSBuild でビルドできますから、一度 GUI でプロジェクトファイルを作った後は、VS のビルドイベントに登録しておけば自動化できます（ビルド時間はかなり伸びますが）。
> ただ、ソリューションのビルドをすべて終えた後のアクションというのはありませんので、ソリューション内でのプロジェクト依存関係で最後にビルドされるプロジェクトのビルドイベントに仕込む必要があるでしょう。

ビルドイベントに登録ですか。そういう手法があるのですね。
現状一番スマートな感じですが、重たくはなりそうです。
しかし、ドキュメントがここまで未整理のままだとは思いもしませんでした。残念です。

引用返信 編集キー/

■57496 / inTopicNo.7)

　Re[5]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ ＰＡＴＩＯ (85回)-(2011/03/01(Tue) 18:14:18)

2011/03/01(Tue) 18:20:18 編集(投稿者)

■No57480 (めめさん) に返信
>
> ＰＡＴＩＯさん
> >私の場合、C#ではなくてC++なのでdoxygenを使っていますが、それに関して特に不満はありません。
> >私の場合、ソースからドキュメントを起こすのではなくて
> >設計書を作成してコーディングするというスタイルなので
> >ソースを記述する時は基本的に設計書がある事が前提になっています。
> >そんなこんなでその方向のアプローチを必要としていないからです。
>
> なるほど。私的にはありなのかもしれません。
> しかし、私は仕様書とプログラムのドキュメントは根本的に用途は別だと思います。
> 確かに、ソースを記述する時にドキュメントが必要であることはないですが、成果物として残すと残さないのでは、だいぶ違うと思います。
> 特にライブラリ系を作りだすと、関数のリファレンスは絶対に必要だと思います。

いえいえ、関数リファレンスも作成します。
ただ単に関数リファレンスをソースのコメントから自動で起こさないというだけの話です。
ですから、成果物として作成することには変わりありません。
基本的にはクラス設計書を元にクラスリファレンスを起こしたりしています。
必要な成果物と言うのはどういう作成方法を取るにしても変わりありません。
ただ、方法論的な違いだけだと思います。
私の場合、自動的に吐き出された資料では相手先がOKをくれないケースが
多かったので大抵の場合、手で起こしていました。

引用返信 編集キー/

■57513 / inTopicNo.8)

　Re[5]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ aetos (357回)-(2011/03/02(Wed) 15:01:37)

■No57480 (めめさん) に返信
> しかし、ドキュメントがここまで未整理のままだとは思いもしませんでした。残念です。

実はねぇ、VS2003 あたりでは確かあったんですよね。HTML を生成する機能が。
「Webページのビルドコメント」とかいう、変な名前の機能でね。
2005 からなくなったんだと思います。
なんでだろうね。

引用返信 編集キー/

■57514 / inTopicNo.9)

　Re[6]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ マサヤ (265回)-(2011/03/02(Wed) 15:13:38)

JavaDocを出されると条件反射でHotDocを上げるのは私だけでしょうか？
http://www.hotdocument.net/faq/man.html
無料ではないので、なんともいえませんが。

引用返信 編集キー/

■57531 / inTopicNo.10)

　Re[5]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ よねＫＥＮ (680回)-(2011/03/03(Thu) 12:29:10)

■No57480 (めめさん) に返信
> ビルドイベントに登録ですか。そういう手法があるのですね。
> 現状一番スマートな感じですが、重たくはなりそうです。

ビルドイベントではなく、外部ツールにコマンドとして登録してはいかがでしょう。
ビルド時に毎回生成するのは無駄が多いように思いますし。
＃どのように登録するかとか、実際に登録できるのかとかは検証していません。アイデアだけです

引用返信 編集キー/

■57535 / inTopicNo.11)

　Re[6]: 最近のC#のドキュメントの作り方

▲▼■

□投稿者/ ＰＡＴＩＯ (88回)-(2011/03/03(Thu) 13:56:23)

今調べて見て気が付いたんですけれど、

doxygenってC#にも対応しているみたいですね。
あんまりじっくり見てなかったから知りませんでしたけれど。

引用返信 編集キー/

トピック内ページ移動 / << 0 >>

このトピックに書きこむ

過去ログには書き込み不可

- Child Tree -