問題タブ [documentation]

私は、実際のコードを実行するのは私だけで、経験の浅い 2 人のプログラマー (自分が経験豊富だと考えるのは恐ろしいことです!) が、プログラム全体を監視し、提案するプロジェクトを開始しようとしています。

私が書いたコードに基づいて、クラスと関数のドキュメントを提供するために使用できる優れた (無料の) システムはありますか? データの構造を理解するのに大いに役立つでしょう。

そのため、一般的に使用されるものに対していくつかの拡張メソッドがあり、それらを文書化する際に、XML コメントでタグを一貫して記述する方法がわからないことに気づきました。summary例えば：

対。

thisしたがって、問題は、その厄介なパラメーターを一貫して参照する方法がわからないことのようです。さらに、これが拡張メソッドであることを明確に示す方法がわかりません (Sandcastle やその他のツールがまだそれらに追いついており、ドキュメントに自動的に注釈を付けて表示できるかどうかわからないため)。後ですべてのマニュアル ドキュメントを削除する必要はありません。

問題は、拡張メソッドを文書化するためのガイダンスは何かということです。正式なガイダンスがない場合、皆さんはどのように対処しますか? 投票していない場合は、何かに投票して、私が何かを続けることができますか? 強迫観念的なコントロールフリークとして、この矛盾は私を怒らせています.

私が過去に見た Latex から html へのコンバーターはかなりひどいものでした。生の html を編集するのは楽しくないし、印刷されたページにうまく変換できないようです。他の人はこの問題をどのように解決しますか? 例 (pdf と html の両方) へのリンクは素晴らしいでしょう。

追加: 別の同様の質問がちょうど尋ねられました:

プロジェクト ドキュメントに使用するフォーマット言語

Apache ServiceMix を始めるための決定的なガイドは何ですか? Web サイトのハウツーとガイドは複雑すぎて、クリーンなスタートを切ることができません。

RDoc で、一定のコメントを表示する方法はありますか? 私のプロジェクトで定数にコメントしたいのですが、それらがRDoc出力に表示されないことに気づきました。定数に関するコメントが含まれている可能性が高いドキュメントを確認しましたが、何も見ませんでした ( http://www.ruby-doc.org/core/classes/Math.html )。

自明であると仮定して、定数の横に実装を示すことは可能ですが、コメントも役立つようです。

誰かが私に完全なASP.NETMVCベータドキュメントを見つけることができる場所を教えてもらえますか？

私は、MSSQL データベース (オブジェクト、テーブル、テーブル データ) の MediaWiki ドキュメントを生成するアプリケーションを作成中です。

私の質問は、どのドキュメント形式を好むか、または作成する必要があるかです。従うべきアイデアが多すぎるので、あなたの答えが私の優先順位を設定する必要があります;)

(SO に関する他のドキュメント関連の質問があることは知っていますが、それらは主にドキュメントの生成方法を扱っており (方法は知っています)、特定のドキュメントの種類やプラットフォームについては尋ねていません)

編集：コメントありがとうございます。外部キーを解析するので、実際にはすでにテーブル関係があります。ただし、完全な相互参照は少しトリッキーかもしれません;)

ただし、この質問は、Word、PDF、ODF など、ドキュメントの種類を尋ねることを目的としていました。あなたの専門的な要件や好みは何ですか?

更新: 生成されたドキュメントの概要

商用ウェブサイトの開発を引き継いでいます。このサイトは、別のプログラマーによって 2 年以上にわたって開発されました。ほとんどが一人の仕事です (サイトの維持と拡張)。他のプログラマーがシステムを見せてくれるまで、2、3 日の移行期間があります。しかし、私が知る限り、ドキュメントはほとんどありません。すべてがコードに含まれています (これは一種の文書化されています)。今のところ質問しようと思っていることは以下のとおりです。

• システムの最も複雑な要素に関する説明
• 全体的なアーキテクチャの説明
• サポート ツールの説明 (IDE セットアップ、単体テスト、展開メカニズム)
• システムのアーキテクチャに影響を与えるために彼が使用した本、ウェブサイト、ポッドキャスト

私が見逃している他のものはありますか？

[編集] みんなありがとう。良い提案を失いました。複数の回答を受け入れることができればよかったのに！さらに、次のことも追加します。

• システムのパフォーマンスを改善するために具体的に何をしましたか? また、現在ボトルネックはどこにありますか?
• それに関連して、システムのセキュリティに関してどのようなことを行っていますか? (あなたは何をしましたか、そして今どこにセキュリティ ホールがありますか)

最後に 1 つ: 開発者は、必要に応じて私の質問に後で答えることができると言っていました。結局のところ、それは彼の「赤ちゃん」です。しかし、私は本当に6ヶ月で彼が引っ越して、彼の可用性がはるかに低下すると思います!

System.Data.Odbc や System.Data.OracleClient などの名前空間を使用する場合、通常、さまざまなデータ リーダー メソッドでは、列に対応する整数を関数に提供する必要があります (例: OracleDataReader.GetInt32 )。

私の質問はこれです。コードがかなり自己文書化されるように、これらの関数を操作する最良の方法は何ですか。現時点では、次の 3 つのオプションがあるように思われます。

これらの手法にはそれぞれ長所と短所があるようで、他の人がどう思うか、またはそれを行うより良い方法があるかどうかに興味があります.

統合しようとしているアプリケーション用にベンダーの 1 つから提供された Web サービスのドキュメントを作成しようとしています。インターフェイスの束は、Web サービス自体で定義されたカスタム オブジェクトです。ベンダーは、このアプリケーションのドキュメントを提供することにかなりの抵抗を示したので、[私のより良い判断に反して] 彼らの仕事を自分で行うことにしました.

彼らが提供したドキュメントは率直に言って恥ずかしいものであり、私はこれをできる限り短くして、質の高いドキュメントをまとめようとしています. 私は彼らのソースにアクセスできないので、nDoc/Sandcastle を介して実行して API ドキュメントを吐き出すことはできないことを知っていますが、(中途半端な家として) 簡単な方法があるかどうか疑問に思っていました定義された各オブジェクト タイプを具体的に反復処理し、メンバーをテキストに反映するユーティリティを作成する必要なく、インテリセンスをテキスト ファイルにエクスポートするにはどうすればよいですか?

これができれば、少なくとも、空欄を埋めるだけの高品質のドキュメント構造が確実に得られるでしょう。すべてのクラス メンバーの IntelliSense をチェックするために Visual Studio を行ったり来たりしなければならないのは、これを行うのに非常に面倒な方法です。

誰にもアイデアはありますか？