問題タブ [documentation]

Visual Studio XML出力からMSDNスタイルのドキュメントを作成する簡単な方法はありますか？
私はこの橋を渡る最初の人ではないことを知っているので、私はそれのために良いxsltを設定するのに十分な忍耐力がありません。

また、最近サンドキャッスルを設置してみましたが、本当に目が離せませんでした。その過程で重要な何かが欠けていたか、それはあまりにも複雑すぎます。

私はそこにいる誰かが本当に素晴らしい非常に単純な解決策を持っていることを知っています。

私のフォーマットによってその段落が読みたくないものになったと思うので、ここで繰り返します。

サンドキャッスルを試してみましたが、セットアップするのに本当に苦労しました。私が本当に心に留めているのは、もっと単純なことです。

つまり、砂の城のプロセスを理解していない限りです。テスターが作業するのに良いものを作るためだけに、私には非常に多くの余分な荷物のように見えました。

私は、さまざまなチームがある程度の重複を持って独自のモジュールで作業する複雑なアプリケーションに取り組んでいます。しばらく前に、Mediawikiインスタンスをセットアップしました。貢献するどころか、実際に使ってもらうのは大変です。

情報を共有することには多くのメリットがあります。それは少なくとも私たちが車輪の再発明をする時間を減らすかもしれません。

wikiはあまり構造化されていませんが、必要なものを検索できる限り、それが問題になるかどうかはわかりません。

ヒントはありますか？

Javadoc のない大きなコードベースがあり、プログラムを実行して基本的な Javadoc 情報 (たとえば、各メソッドのパラメーター write @param...) を含むスケルトンを作成したいので、残っているギャップを埋める必要があります。

これに対する良い解決策を知っている人はいますか？

編集：

JAutodoc は私が探していたものです。Eclipse プラグインである Ant タスクがあり、テンプレート定義に Velocity を使用します。

それでおしまい。関数またはクラスを文書化する場合は、定義の直後に文字列を配置します。例えば：

しかし、モジュールはどうですか？file.pyの機能を文書化するにはどうすればよいですか？

私はD2007を使用しており、HelpInsight機能（D2005以降に提供）を使用してソースコードを文書化しようとしています。私は主にHelpInsightツールのヒントを機能させることに興味があります。さまざまなWebサーフィンと実験から、私は次のことを発見しました。

1. トリプルスラッシュ（///）コメントスタイルの使用は、他の文書化されたコメントスタイルよりも頻繁に機能します。すなわち： {*! comment *}そして{! comment }
2. コメントは、その目的の宣言の前に置く必要があります。ほとんどの場合、これはコードのインターフェースセクションにそれらを配置することを意味します。（明らかな例外は、現在のユニットの外部からアクセスできないため、実装ブロックで宣言されているタイプと関数の場合です。）
3. 最初のコメントは関数に対するものにすることはできません。（つまり、タイプ用である必要があります。または、少なくとも、HelpInsight機能が機能する前にパーサーが「type」キーワードを認識している必要があるようです）

これらの「ルール」に従っているにもかかわらず、Help-insightが私が書いたコメントを見つけられないことがあります。1つのファイルで正しいHelpInsightツールのヒントが生成されませんが、このファイルを別のダミープロジェクトに含めると、正しく機能します。

HelpInsightを機能させるためのその他の指針/コツはありますか？

私は、C または PHP コードのドキュメントを作成するために Doxygen が好きです。/* .. */私は近日中に Python プロジェクトを予定していますが、Python にはコメントがなく、独自の自己文書化機能も備えていることを覚えていると思います。

私は Doxygen に精通しているので、それを使用して Python ドキュメントを作成するにはどうすればよいですか? 特に注意しなければならないことはありますか？

Unix の時代には、最初にマニュアル ページを読まずにソフトウェアを終了することさえできませんでした。その後、一貫したメニュー レイアウトとキーボード ショートカットを備えた Mac と Windows が登場しましたが、アプリで可能なすべての操作を説明した紙のユーザー マニュアルがシュリンクラップ ボックスに同梱されていました。インターネットの後、ヘルプ ファイルは html ドキュメントになりました。

最近のWeb 2.0アプリケーションでは、ヘルプはほとんど表示されません。そこにある場合でも、特定のタスクを説明しているだけです。言い換えれば、アプリはユーザーベースの常識や考えさせない要素にもっと依存しています.

何年も前に Microsoft はInductive User Interfaceと呼ばれる概念を思いつきました。これは基本的にプログラマーにアプリ自体に指示を出すように指示するものですが、そのアイデアがどれほど人気が​​あるかはわかりません。

ヘルプ ファイル、ユーザー マニュアル、および F1 キーを使用した状況依存のオンライン ヘルプは無効ですか? ユーザーが UI から何をすべきかを見つけることができなかった場合、私は失敗しましたか? そうでない場合、どの程度の支援を提供する必要がありますか? (デスクトップと Web アプリの両方)

編集: ドキュメンテーション/ヘルプ ファイルは、アジャイル開発手法とどのように調和しますか? たとえば、多数のスクリーンショットを廃止する可能性のある UI の変更を行う前に、開発者はよく考えるべきでしょうか?

API ドキュメント (「パブリック関数の javadoc」など) で、従来のドキュメントと同様に「値の制限」の説明をよく目にしますか?

注：コード内のコメントについて話しているのではありません

「値の制限」とは、次のことを意味します。

• パラメーターは null 値 (または空の文字列、または...) をサポートできますか?
• 「戻り値」はnullになる可能性がありますか、それともnullにならないことが保証されていますか（または「空」になる可能性がありますか...）？

サンプル：

私がよく目にするのは（ソースコードにアクセスできない場合）次のとおりです。

私が見たいのは次のとおりです。

私のポイントは次のとおりです。

getReaderNames() 関数を含むライブラリを使用する場合、多くの場合、その機能を推測するために API ドキュメントを読む必要さえありません。しかし、私はそれを使用する方法を確認する必要があります。

この関数を使用するときの私の唯一の懸念は、パラメーターと戻り値に関して何を期待する必要があるかということです。パラメータを安全に設定し、戻り値を安全にテストするために知っておく必要があるのはこれだけですが、API ドキュメントでそのような情報を目にすることはほとんどありません...

編集：

これは、チェックされた例外またはチェックされていない例外の使用に影響を与える可能性があります。

どう思いますか ？値制限とAPI、それらは一緒に属しますか?

C# ドキュメントでは、タグを使用して MSDN と同様の出力を生成できます。クラス、メソッド、およびプロパティの上の /// (トリプル スラッシュ) コメント領域内で使用できるタグのリストは何ですか?

Solaris/Linux でのスレッド化について説明しているさまざまなドキュメントがありますが、現在は Windows の実装について説明しています。私はこれに興味を持っています。これほど重要なことが (一見) 文書化されていないのは奇妙に思えます。

スレッド化は異なる OS で同じではありません' - 「Write Once, Run Anywhere」はスレッド化には当てはまりません。

http://java.sun.com/docs/hotspot/threads/threads.htmlを参照してください。