apiドキュメントは、"価値の限界":いわ?

Question

いましばしば見のAPIドキュメントとしての"javadocの公益的機能"を例に説明の値の制限"などのクラシック書類?

注意： というわけではありません コメント内のコード

による"価値の限界"とは、:

• なパラメータでnull値は、空の文字列やダウンロードも可能です。)?
• はa'の戻り値はnullを取ることができますし、又は保証されない。nullの場合(または"空"やダウンロードも可能です。)?

サンプル

私がよくなるソースコードへのアクセスは次のとおりである

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

私 という することはできない。

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

私は:

ご利用する場合は、図書室、getReaderNames()機能で、私はしばしばないものを読み込む必要があり、APIドキュメントに思うのです。もうすることを確実にする必要があり 使い方を指導することもでき.

かりたいときにこの機能を使用するには:何をすべきかのパラメータを返します。その全てを知る必要があり安全に設定私のパラメータの安全試験の返り値が、私はほとんどないこのような情報のAPIドキュメント...

編集：

この影響を与えることができご利用いた チェックボックスやチェック例外.

いかがですか？値の制限およびAPIは、所属しているとはありませんか？

Answer 1

いと思い ができ 所属とがな してい に帰属します。おシナリオでは、そのようなことは、あってはならないことでその限界を明確にした実行計画が定められてように表示され、生成されたAPIドキュメントおよび頭に付けた場合の言語/IDEを支援します。

思いを語る。例えば、Adaは、ネイティブデータタイプに制限整数が定義する整数型の変数を明示的に示されます（い）内の数値です。その場合、データ型そのものを示します。でも可視域および含通のAPIドキュメントおよび頭に付けがなされるもの開発者を指定します。

しかし、言語のようなJavaとC#のないこのタイプの持ち込みが禁止されている整数の開発者が指定するコメントする情報となるべきであり、公的資料。

Answer 2

と思い、それを境界条件があるのAPIとなります。しかし、私(わん)に行くる一方で、さらに一歩踏み込からのバイオエタノールの方がnull値をいたします。次のいずれかを示す例外をスローします、もしく説明に期待される成果は、境界値が渡されます。

っていないことで良いと思うユーザのクラスです。でも難しいスしなければならない場合は、契約方法の提示の変更などは、null値が変更不可)...い勤勉なもの更新のドキュメントを変更したときに意味の研究"に関するお問合せ

Answer 3

質問1

いましばしば見のAPIドキュメントとしての"javadocの公益的機能"を例に説明の値の制限"などのクラシック書類?

ほとんどないですね。

質問2

かりたいときにこの機能を使用するには:何をすべきかのパラメータを返します。その全てを知る必要があり安全に設定私のパラメータの安全試験の返り値が、私はほとんどないこのような情報のAPIドキュメント...

場合に使用した機能がいないと私は期待し RuntimeException によってスローされる方法または RuntimeException 別のものであるもののこれまでのプログラム。

コメントなど @param aReaderNameRegexp filter in order to ... (can be null or empty) しんでいただけるように実施 シンプルなテキストエディタには に人間の言語中 Javadoc.

利用のJavadocを実施シンプルなテキストエディタには使用され iContract, 現在復活へ JcontractS, るように指定し 不変量の前提条件postconditions, で、正式の方法に比べ、スカイプ同士(パソコン間)よります。

質問3

この影響を与えることができご利用はチェックボックスやチェック例外をスローしました。いかがですか？値の制限およびAPIは、所属しているとはありませんか？

Java言語にはあまりないシンプルなテキストエディタに特徴ですと、誘惑されることの利用 Execption がおっしゃるとおりですね、という事実を認識して 時の選択の確認、チェック例外.も利用する場合もあるでしょうチェック IllegalArgumentException, IllegalStateException, 、または利用する場合もあるでしょうユニットの試験が、大きな問題はコミュニケーションの取り方等その他のプログラマーなどがデザインによる契約として考慮されるべきである。前に契約書を変更しております。

Answer 4

ると思うん、いいコメントのヘッダファイル(c++)arcordingly.

のほか、有効な入力/出力/返りコメント、または例外をliklyスローされる機能(いしばしば使いたいする返り値---じ値を返す、例えエラーコード)

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Answer 5

@火ランサーエボリューション:ます。私は忘れてもうとして有効利用することで、特にチェック'実行'例外がこの公開方法が投げ

@Mike Stone:

い勤勉なもの更新のドキュメントを変更したときに意味の研究"に関するお問合せ

ゃいくことを願って 公開APIドキュメント は少なくとも更新しい変化に影響する契約の機能--います。ない場合は、APIに書き落とします。

追加食品のお考えやん@スコットDorman)のうち、偶然に 将来のjava7注釈

うなことです。この間の境界条件を'しているのではなく、書類のかかわりを深めるべきであるのAPI自体は、自動的に利用、編集時に適切に'を主張する'生成されます。

この場合、'@CheckForNull'のAPIのライターの機能でかなものを記録です！とばの意味の変化、そのAPIを反映する変更（いなり@CheckForNull"のインスタンス)

そういうアプローチこの文書は、'境界条件では、どんな製品を設計-デザインは必須です。

しかし、それはカバーしていない特殊値の返却オブジェクトの機能です。その、 完全 書類が必要です。