タグ付けされた質問 「javadocs」

最近、私が現在扱っているコードベースの部分のリファクタリングに取り組んでいます-自分自身をよりよく理解するためだけでなく、コードに取り組んでいる他の人にとってそれをより簡単にするために。 私は、自己文書化コードは素晴らしいと考える側に傾く傾向があります。私はちょうどそれがきれいだと思うし、コードがそれ自体のために話すなら、まあ... それは素晴らしいです。 一方、javadocsなどのドキュメントがあります。私もこれが好きですが、ここのコメントが時代遅れになるという特定のリスクがあります（もちろん一般的なコメントも同様です）。ただし、それらが最新の場合、複雑なアルゴリズムを理解するなど、非常に役立ちます。 これのベストプラクティスは何ですか？自己文書化コードとjavadocsの間のどこに線を引きますか？

18 java  documentation  refactoring  javadocs 

メソッドまたはAPIがコードベースにあるが、実装が完全ではないか、変更される可能性が高いため、使用すべきではないという意味で、「非推奨」と似ているが異なる用語はありますか？（ええ、私は知っています、これらの方法は公開すべきではありません、やだやだやだ。自分の状況を作り出したのではなく、それを最大限に活用しようとしています。） 人々は何を提案しますか？実験的、不完全、他の何か？ まだ流動的なこのAPIのjavadocドキュメントを構築している場合、@ deprecatedタグを使用する必要がありますか、それともより良い規則がありますか？私にとって@deprecatedは、このAPIが古く、新しい優先メカニズムが利用可能であることを意味します。私の状況では、代替手段はありませんが、APIの一部のメソッドは終了していないため、使用しないでください。この時点では、それらを非公開にすることはできませんが、ドキュメントに明確な警告を記載したいと思います。

12 documentation  terminology  api  documentation-generation  javadocs 

JavaDocには次のX509Certificate getSubjectDN()ように記載されています。 Denigrated、getSubjectX500Principal（）に置き換えられました。 もう使用すべきではないがDenigratedではないメソッドのDeprecatedに慣れています。コメントで閉じられたこの特定のケースに関するバグレポートを見つけました： これはバグではありません。「非推奨」は、深刻な場合にのみ使用することを意図しています。 Deprecatedのメソッドを使用している場合、一般的に推奨されるアクションはメソッドの使用を停止することです。 メソッドがDenigratedとしてマークされている場合の推奨アクションは何ですか？

11 java  terminology  javadocs 

私は、基本的なよく知られている文字列メトリックの実装を提供する小さなライブラリに取り組んでいます。主に私自身の教育のために。ですから、少し時間があるときに開発が行われます。 このため、私はほとんどのプロセスを自動化しているので、バージョンをリリースするのに、手間をかけずに頻繁に行うことができます。ただし、例が含まれているため、Java docの保守は依然として負担です。 APIが進化するにつれ、各例を手動で繰り返し確認する必要があります。これを行うより良い方法はありますか？ ドキュメントと例を別のプロジェクト（Caliperチュートリアルなど）に移動することを検討したので、通常のコードと一緒にリファクタリングしてコンパイルできます。ただし、これにより、ドキュメントが目的のクラスから移動します。 そうそう。ケーキも食べてみたいです。：D * <h2>Tokenization</h2> * * Tokenization cuts up a string into tokens e.g. * <code>chilperic ii son of childeric ii</code> is tokenized into * <code>[chilperic, ii, son, of, * childeric, ii]</code>. Tokenization can also be done repeatedly by tokenizing * the individual tokens e.g. * …

9 java  documentation  javadocs 

JavadocをDRYで記述したい。しかし、Javadocに関するOracleのドキュメントでは、オーバーロードメソッドのコメントに同じことを再度記述しています。繰り返しは避けられませんか？

9 documentation  comments  dry  javadocs 

私は大学の研究室のマニュアルで以下に出くわしました： javadocを生成してクラスのインターフェースを調べる必要があるので、提供される操作を確認できます（コードを自由に見てください。ただし、他の誰かのコードを使用する場合は、ここでは、javadocではなくjavadocから作業する必要があります）可能な限りコード）。 なぜそうなのか理解できません。javadocが古くなっている可能性があるか、コードの機能を不適切に説明している可能性があるためです。確かにソースコードを見て、javadocコメントを読むのが最善でしょうか？ javadocのみを読むことが最善の方法である理由、またはその理由はありますか？

8 source-code  comments  javadocs 

インラインJavaドキュメントに代わる優れた方法は何でしょうか。つまり、Javaソースファイルに何らかの方法でマップされた個別のドキュメントファイルを持つことができますか？ 私はコードに散らばっている巨大なコメントセクションが好きではありません。

8 java  documentation  javadocs