問題タブ [code-documentation]

これが最も重要な問題ではないことは知っていますが、注釈の前または後にjavadocコメントブロックを配置できることに気づきました。コーディング標準として何を採用したいですか？

作成したばかりの新しいコードを調べて、NDoc スタイルのコメントをクラスとメソッドに追加しています。参照用にかなり優れた MSDN スタイルのドキュメントを生成したいと考えています。

一般的に、クラスやメソッドにコメントを書く際の良いガイドラインは何ですか? NDoc コメントは何を言うべきですか? 彼らは何を言うべきではありませんか？

.NET フレームワークのコメントに書かれている内容を見ていると、すぐに古くなってしまいます。自分自身を導くための良いルールがあれば、ドキュメントをはるかに速く完成させることができます.

c# .net でアプリケーションを開発し、イントラネット内で展開できるようにすることを目指しています。私たちはそれに沿った確かなドキュメントを用意したいと考えていますが、これをドキュメント化するのに最適なプラットフォームがわかりません. このプロセスを容易にするツールはありますか?

Doxygen、Htmlhelp、または Dr Explain について知りましたが、何を使用すればよいかまだ確信が持てません。

publicVisual Studioには、一部のメンバーにXMLドキュメントがない場合に、コンパイラーの警告を大量に吐き出す優れた機能があります。

internal非メンバーの場合も同じか、それ以上にしたいと思いますがprivate、残念ながら、これまでのところ、XMLドキュメントを必要とする可視性のレベルを構成する方法を見つけることができませんでした。

私は同じ質問がずっと前に尋ねられたことを認めます、しかしOPは単一の答えを得ませんでした。

Xcode で自分のコードのクイック ヘルプ エントリを作成するにはどうすればよいですか? Java をコーディングするときの Eclipse 機能のようなコーディング サポートとしてそれが欲しいだけです。Eclipse では、メソッドを別の場所に移動すると、メソッドの上に入力したコメントが表示されます。

Xcode に相当するものは「クイック ヘルプ」のようです。

Doxygenを使用する以外に本当に方法はありませんか? Doxygen は、私が取り組んでいる小さなプロジェクトにはやり過ぎのようです。現時点では、クイック ヘルプを完全に入力するだけでよいことは確かです。そのため、「プロジェクトのドキュメントを作成する必要があります」などのヒントは避けてください。

このトピックで見つけたのはこの質問だけだったので、助けていただければ幸いです。

しかし、ご覧のとおり、解決策はありません。

私たちは開発チームであり、コードを文書化する必要があります。各開発者は、モジュールとして呼び出すことができるコードの一部に取り組みます。この仕様が記載されたドキュメントが必要です

1. 実装と使用が簡単であること
2. 各開発者は自分の作業を文書化し、別の開発者がモジュールについて知る必要がある場合、元の開発者に文書について尋ねる義務はありません。彼/彼女は自分でドキュメントを見つけることができるはずです.
3. ドキュメント全体を検索できるはずです。

これについて何か提案はありますか？

まず、PHP ソースからドキュメントを生成する方法について質問しているわけではありません。これは、Doxygen や PHPDocumentor などのライブラリを使えば簡単です。私が探しているのは、クラス、メソッド、プロパティなどのインライン phpdoc ベースのコメント スタブを自動的に生成する方法です。これを実行できる既存のライブラリはありますか? 私は少し検索を行いましたが、何も思いつきませんでした。

自分で書いて掻きたいかゆみがあるので聞いているだけです。私は一度に何時間もコードを大量に作成し、最後のステップとしてドキュメントを保存することに費やす傾向があります (わかっています。問題は、インライン ドキュメントの重要性を認識していても、8 時間連続でコーディングし、数十のメソッドとプロパティを持つ 12 のクラスを作成した後、金切り声を上げて停止し、何かを書き始めなければならないのは少し気が進まないことです。

明らかに、完全なドキュメントを自動的に作成することはできません。クラス、プロパティ、メソッドの詳細な説明などは、手動で入力する必要があります。しかし、リフレクションを使用すると、空白を埋めるプレースホルダーを含むコメント スタブを作成するのに十分な情報を簡単に得ることができます。

誰かがこのような解決策を探すのを手伝ってくれたら、素晴らしいです。そうでない場合は、新しい Github リポジトリを作成して、コミュニティに役立つものを提供します。:)

私は現在JSDoc Toolkitを使用してコードを文書化していますが、うまく適合しません。つまり、名前空間を適切に記述するのに苦労しているようです。それぞれのファイルに 2 つの単純なクラスがあるとします。

lib/database/foo.js:

そして、継承されたものlib/database/bar.js：

生成されたドキュメントでは、これは単純にFooandとして出力されBar、先頭のdatabase(or lib.database) は省略されます。これは、グローバル スコープにすべてが含まれていない場合に非常に必要です。

投げてみましたが@namespace database、うまくいき@name database.Fooません。

JSDoc 出力をより適切なものにするためのアイデア、または Node.js でより適切に機能するまったく異なるツールを作成するためのアイデアはありますか? （私はNatural Docs、JSDuckを簡単に見て、かなり時代遅れに見える他のかなりの数を簡単に調べました...）

私はかなり単純なクラスのこのドキュメントを書きましたが、十分に明確ではないと感じています。私は何かを変更する必要がありますか？

私はhttp://www.phpdoc.org/を見ていますが、皆さんが何を役に立ったと思っているのでしょう。私たちのコードを文書化するのに役立つものだけでなく、サイトで頻繁に実行される手順とタスクも必要です。Linux/PHP/MySQL 環境でこれに最適なソリューションは何ですか?