問題タブ [documentation]

基本的なリクエストは次のとおりです。

• 人間が読める / テキスト形式 (簡単なバージョン管理のため)
• オンライン（コラボレーション用）
• 簡単な書式設定 (マークダウンはOK、html は多すぎる)
• 厳密な書式設定 (作成者が新しいタイプのタイトル、箇条書きなどを発明しないようにするため)
• PDF、HTMLにエクスポート可能
• 簡単なバックアップと展開 (読み取り専用バージョンとしてお客様のサイトに「展開」できるようにするため)

ある種の wiki エンジンを使用することを考えていますが、ストレージにファイルを使用するか、顧客への「展開」の他の手段が必要であり、インストール/メンテナンスが簡単である必要があります。また、無料/安価である必要があります（合流点は高すぎます）

助言がありますか？

編集: コードを文書化するためのツールを探しているわけではありません。Sandcastle を使用してカバーしています。

リリース ノートとは何のためのもので、誰が読むものですか? 現在のリリースのバグ修正を吐き出すだけで自動化する必要がありますか?それとも、人間が慎重に編集する必要がありますか? では、ソフトウェアのリリース ノートに関するベスト プラクティス (理由付け) へのリンクを持っている人はいますか?

ソフトウェアの設計とアーキテクチャを文書化するためのベストプラクティスとソフトウェアツールは何ですか

1. Javaまたは.NETに基づくPCベースのアプリケーション？

2. VxWorksまたはEmbeddedLinuxまたはWindowsCEに基づく組み込みアプリケーション？

私が念頭に置いているツールの1つは、エンタープライズアーキテクトです。それは良い選択ですか？

顧客に公開している API (.Net) にコメントしようとしています。XML コメントを使用し、SandCastle を介して抽出することでこれを行っています。

これはすべてうまくいきますが、私は API の単体テストを行っており、これらのコードを example タグに配置するとよいと考えました。

単体テストコードを抽出してサンプルタグに配置する良い方法を知っている人はいますか? または、誰かがより良いアイデアを持っていますか?

もちろん単体テストはAPIで再配布していますが、ドキュメントにまとめていただけると助かります。

Merb については良いことしか読んだことはありませんが、Web サイトのドキュメントは基本的に API リファレンスであり、現在、既刊の書籍はありません。

Merbに関するリソースはありますか?

コードを読み始めると思いますが、別の情報源があるといいですね

XML コメント/ドキュメントでクラスのメンバーを参照するには、次のタグを使用する必要があります。

ここでよりよく説明されています。

インデクサーをどのように参照しますか?

つまり、次のようなメンバーです。

前もって感謝します。

JVM 内部、CLR 内部などに関する多くの参考文献に沿って、Javascript エンジンの内部に関する書籍、記事、論文を探しています。 、しかし、そこに本や他の「ガイド付きツアー」ドキュメントがある場合は、それらを最初に読みたいと思います. ありがとう。

常識的には、Doxygen コメント ブロックは、クラス、構造体、列挙型、関数、宣言があるヘッダー ファイルに配置する必要があります。これは、ソースなしで配布されることを意図したライブラリ (オブジェクト コードを含むヘッダーとライブラリのみ) の妥当な議論であることに同意します。

しかし...私は、完全なソースコードで使用される社内の (または自分自身のサイドプロジェクトとして) ライブラリを開発しているときに、正反対のアプローチを考えていました。私が提案するのは、実装ファイル (HPP、INL、CPP など) に大きなコメント ブロックを配置して、ヘッダーで宣言されたクラスと関数のインターフェイスが乱雑にならないようにすることです。

長所：

• ヘッダー ファイルの混乱が少なくなり、関数の分類のみを追加できます。
• たとえば、Intellisense の使用時にプレビューされるコメント ブロックは衝突しません。これは、.H ファイルに関数のコメント ブロックがあり、同じ .H ファイルにそのインライン定義がある場合に見られる欠陥です。ただし、.INL ファイルから含まれています。

短所：

• (明らかなもの) コメント ブロックは、宣言があるヘッダー ファイルにはありません。

それで、あなたは何を考え、おそらく提案しますか？

おはよう、午後、夕方、または夜 (タイムゾーンによって異なります)。

これは、C# 内の XML コメントに関する一般的な質問です。私は自分のプログラムにコメントすることにあまり熱心ではありませんでした。私は常に、より詳細な変数/プロパティ/メソッドの命名者であり、コード自体に語らせてきました。かなり紛らわしいものをコーディングしている場合はコメントを書きますが、ほとんどの場合、多くのコメントは書きません。

.NET、Sandcastle、および codeplex のヘルプ ファイル ビルダーの XML コメントについて読んでいたところ、自分のコードを文書化し、自分のコードを掘り下げなければならない人のために素敵で役立つドキュメントを生成したいと思うようになりました。私がもうここにいないときのコード。

私の質問は、標準と慣習についてです。「良い」XML コメントのガイドはありますか? すべての変数とプロパティにコメントする必要がありますか? すべての方法？私は基本的に、サンドキャッスルによって適切なドキュメントにコンパイルされる優れたコメントを書く方法に関するヒントを探しているだけなので、他のプログラマーが私のコードで作業する必要があるときに私の名前を呪うことはありません。

あなたのアドバイスと提案を事前にありがとう、Scott Vercuski