問題タブ [documentation-generation]

HTMLのFAQ（例）があり、質問はお互いをよく参照しています。つまり、質問を挿入/削除/再配置するたびに、番号が変更されます。LaTeXは、\labelと\refを使用してこれを非常にエレガントに解決します。アイテムに単純なタグを付けると、LaTeXは最終的なドキュメントで数値に変換することを心配します。

人々はそれをHTMLでどのように扱いますか？

追加：実際に番号でアイテムを参照する必要がない場合、これは問題ではないことに注意してください。この場合、次のタグを設定できます。

<a name="foo">

そしてそれにリンクする

<a href="#foo">some non-numerical way to refer to foo</a>。

しかし、「foo」には、たとえばリストから自動生成された番号があると想定しており、<ol>その番号を使用して参照およびリンクしたいと思います。

ASP.NET MVCアプリケーションのさまざまなプロセスと依存関係を視覚的に示す簡単な中央ドキュメントを作成したいと思います。たとえば、「サインアップ」アクションメソッドがPOSTデータを取得したときにサービスが呼び出され、復号化と検証が行われ、最後にすべてがリポジトリを使用して保存され、電子メールサービスが電子メールを送信します。メソッド呼び出し、インスタンス名、およびパラメーターを示すフローチャートだけでも、最初から最後まで（分岐を使用して）優れています。

これを自動的に実行できるものはありますか（たとえば、各アクションメソッドに対して）、それとも手動で実行するか、特定のツールを使用しますか？それの要点は、新しい開発者に、アプリケーションにどのような種類の依存関係とフローが存在するかをすばやく理解させることです。

ありがとうございました

dojoを開発している人たちはどのようにしてドキュメントを作成するのですか？

ナイトリービルドから、すべてのコメントを含む非圧縮のjsファイルを取得できます。また、そこからhtmlまたはxmlを生成する何らかのドキュメントスクリプトがあると確信しています。

utilsフォルダーにあるjsdocを使用していると思いますが、使用方法がわかりません。jsDocツールキットは/**commenting**/、元のdojoファイルとは異なる表記法を使用します。

ご協力ありがとうございます

私は保険会社で働いています。当社には、約 150 人の従業員と一部のプロバイダー (アウトソーシングやカスタムメイドのアプリがほとんど) で構成される独自の開発部門があります。私たちの会社では、私のチームが非機能ロジック ライブラリと呼んでいるものを作成しました。つまり、セキュリティ、Web サービス、ロギング、メッセージングなど、私たちの部門のすべての開発チームに共通することを処理するためのソフトウェア ライブラリです。ほとんどの、またはこれらのツールは、ゼロから作成されるか、デファクト スタンダードを採用したものです。たとえば、ロガーは Log4J に基づくアペンダーであり、ログ メッセージを DB に保存します。また、アプリケーションで使用するライブラリ (たとえば、Web サービスが使用するフレームワーク) も定義します。私たちは、組織全体でほとんど JavaEE と Oracle AS を使用しています (いくつかの Websphere アプリケーション サーバーを使用)。

これらのプロジェクトの多くは、アーキテクチャ (ユースケース、UML 図など) が文書化されており、通常、生成された文書が利用可能です。私たちが見たのは、私たちが提供するライブラリを使用するのが難しい場合があり、常に質問をしたり、単にそれらを使用していないということです。

そのため、彼らのために、よりわかりやすいドキュメントを作成する予定です。私の質問は次のとおりです。ソフトウェア ドキュメントに含める必要があるベスト プラクティスまたはチェックリストは何ですか?

何かが頭に浮かぶ：

1. API リファレンス ガイド
2. クイックスタートチュートリアル
3. API 生成ドキュメント。
4. 検索可能である必要があります
5. Web アクセス

他に何が必要ですか？また、あなたの経験に基づいて、この種のドキュメントを維持 (最新の状態に保つ) および公開するための最良の方法は何ですか?

これは、 Sphinxに関する以前の質問の一般化されたバージョンです。

クラスと関数を含むモジュールまたはパッケージを再帰的に自動文書化する方法はありますか？

関数ごとにautofunctionorディレクティブを追加するのはばかげていると思います。automoduleプロセスを自動化する方法が必要です。そうしないと、Sphinxを使用する意味がまったくわかりません。

明確化： 代わりに：

すべてのメソッド名を手動でカットアンドペーストし、それに応じてドキュメントを更新する必要があるため、次のようなコマンドが必要です。

データベースパッケージをAPIとしてより完全に文書化しようとしています。私たちが欲しいのは、PL/SQL用のJavaDocsのようなものです。私はそこにいくつかのツール（pldoc、plsqldoc）を見てきましたが、それらを使用する人々からそれらがどのように比較されるか知りたいです。

コメント表示を使用して任意の言語に対して、簡単で、親しみやすいハイパーリンク付きのドキュメントを生成するドキュメント システムはありますか? このようなシステムには、コメントを認識して構造を生成するための正規表現またはパターンが与えられるだけです。

私は1つを書くつもりでしたが、すでに1つあるに違いないと考えました。

たくさんのメンバーがいる本当に大きな.javaクラスファイルが1つあります。このためのHTMLドキュメントを作成して、メンバータイプで並べ替えずに、外観順にメンバーを表示するにはどうすればよいですか？（メソッド、定数、変数）

たとえば、私のJavaコードが次の場合：

Javadocは、メンバーをアルファベット順に並べ替えてタイプ別に並べ替えるため、メンバー間の関係は失われます。

また、よりスマートな機能で生成されるドキュメントはありますか？お気に入り：

1. メソッドと変数の近くのコメントの抽出
2. メソッドのサイズ-コード行

タイプ（プライベート/パブリック/メソッド/変数）によるメンバーの並べ替えを完全に無効にし、宣言された順序に基づいてメンバーを出力できるDoxygenオプションはどれですか？