パラメータ化されたオブジェクトに変更を適用するメソッドを想像してください。たとえば、マップoderリストが渡されました。Javadoc内のメソッドパラメータに適用される変更を記述する方法はありますか?
パラメータのコピーを作成して返さない場合は、このメソッドのJavadocおよびこれらの変更を示すパラメータを通知するのが最善の方法です。
@varparamや@refparamのような別の@paramタグを考えることができます(他のプログラミング言語の参照渡しのキーワードについて)。
質問:Javadocでこれらのヒントを行う一般的な方法はありますか?パラメータに変更を適用するのはどれほど一般的ですか?私はこれが頻繁に現れる問題かもしれないと思う。
実行時に何とか自分自身を変身させるコードがない場合は、現在のタグとオプションでは不十分な理由がわかりません。 –
@ TadijaBagarić問題は、それが容易に見過ごされ、変更がパラメータに適用されるということです。理由はちょうど悪いコードかもしれません。修正プログラムとして、Javadocを調整するプロジェクトが、このような悪いメソッドの動作を排除するためにリファクタリングを開始するよりも良い場合があります。 –
同様の注意点として、約20年前、 '@destrecated'タグと同様に動作する' @ unstable'タグを提案しましたが、却下されました。それはまだ開発中であるとしてAPIにフラグを立てて、将来の変更を壊すかもしれないと警告しました。しかし、タグが設定されると、タグを追加することにかなり抵抗していました。 –