Javadoc إعادة استخدام وطرق المحملة




javadoc شرح (4)

ضع الوثائق على الواجهة ، إذا استطعت. سيتم بعد ذلك أن ترث الفئات التي تقوم بتطبيق الواجهة javadoc.

interface X(){
 /** does fooish things */
 void foo();
}

class Ax implements X{ //automatically inherits the Javadoc of "X"
 @Override 
 public void foo(){/*...*/} 
}

في حالة رغبتك في وراثة الوثائق وإضافة الأشياء الخاصة بك إليها ، يمكنك استخدام {inheritDoc}:

class Bx implements X{
 /**
  * {@inheritDoc}
  * May fail with a RuntimeException, if the machine is too foo to be true.
  */
 @Override 
 public void foo(){/*...*/}
}

انظر أيضًا: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

الآن كما فهمت ، هذا ليس بالضبط ما تريد (تريد تجنب التكرار بين الأساليب في نفس الطبقة / الواجهة). لهذا يمكنك استخدامsee أوlink ، كما هو موضح من قبل الآخرين ، أو قد تفكر في التصميم الخاص بك. ربما ترغب في تجنب التحميل الزائد على الطريقة واستخدام طريقة واحدة باستخدام كائن معلمة بدلاً من ذلك ، مثل:

public Tree addTree(TreeParams p);

ليتم استخدامها على هذا النحو:

forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));

قد ترغب في إلقاء نظرة على هذا النمط المحول للنسخ هنا:

https://brixomatic.wordpress.com/2010/03/10/dealing-with-immutability-and-long-constructors-in-a-fluent-way/

واعتمادًا على كمية تركيبات المعلمات ، يمكن أن تكون هذه الطريقة أسهل وأكثر نظافة ، نظرًا لأن فئة Params يمكن أن تلتقط الإعدادات الافتراضية ولها javadoc لكل معلمة.

أقوم بتطوير API مع العديد من الأساليب المسماة بشكل مماثل والتي تختلف فقط عن طريق التوقيع ، والتي أعتقد أنها شائعة إلى حد ما. كلهم يفعلون نفس الشيء ، فيما عدا أنهم يقومون بتهيئة القيم المختلفة عن طريق الإعدادات الافتراضية إذا كان المستخدم لا يريد تحديدها. كمثال سهل الهضم ، والنظر في

public interface Forest
{
  public Tree addTree();

  public Tree addTree(int amountOfLeaves);

  public Tree addTree(int amountOfLeaves, Fruit fruitType);

  public Tree addTree(int amountOfLeaves, int height);

  public Tree addTree(int amountOfLeaves, Fruit fruitType, int height);
}

الإجراء الأساسي الذي تقوم به كل هذه الأساليب هو نفسه. تزرع شجرة في الغابة. هناك الكثير من الأمور المهمة التي يحتاجها مستخدمو واجهة برمجة التطبيقات لمعرفة المزيد عن إضافة الأشجار لجميع هذه الطرق.

من الناحية المثالية ، أود أن اكتب كتلة Javadoc واحدة يتم استخدامها من قبل جميع الطرق:

  /**
   * Plants a new tree in the forest. Please note that it may take
   * up to 30 years for the tree to be fully grown.
   *
   * @param amountOfLeaves desired amount of leaves. Actual amount of
   * leaves at maturity may differ by up to 10%.
   * @param fruitType the desired type of fruit to be grown. No warranties
   * are given with respect to flavour.
   * @param height desired hight in centimeters. Actual hight may differ by
   * up to 15%.
   */

في مخيلتي ، يمكن للأداة أن تختار بطريقة سحرية أي منparams تنطبق على كل طريقة من الطرق ، وبالتالي توليد مستندات جيدة لجميع الأساليب في وقت واحد.

مع Javadoc ، إذا فهمت ذلك بشكل صحيح ، كل ما يمكنني فعله هو نسخ ولصق كتلة javadoc نفسها خمس مرات ، مع قائمة معلمات تختلف قليلاً عن كل طريقة. هذا يبدو لي مرهقة ، ومن الصعب أيضا الحفاظ عليه.

هل هناك طريقة اخرى؟ بعض التمديد لجافادوك التي لديها هذا النوع من الدعم؟ أم أن هناك سببًا وجيهًا لعدم تأييد هذا الأمر؟


أنا لا أعرف أي دعم ، ولكن ، أود أن javadoc الطريقة بالكامل مع معظم الحجج ، ومن ثم الرجوع إليها في javadoc الأخرى مثل ذلك. أعتقد أنه واضح بما فيه الكفاية ، ويتجنب التكرار.

/**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */

أود فقط توثيق طريقة "الأكمل" (في هذه الحالة addTree(int,Fruit,int) ) ثم في JavaDoc لطرق أخرى الرجوع إلى هذه الطريقة وشرح كيفية / التي يتم استخدام قيم الافتراضات للوسائط غير المقدمة.

/**
 * Works just like {@link ThisClass#myPow(double,double)} except the exponent is always 
 * presumed to be 2. 
 *
 * @see ThisClass#myPow(double,double)
 */
 static double myPow( double base );

من المحتمل أنه لا توجد طريقة قياسية جيدة ، حتى إن شفرة المصدر JDK9 ببساطة تقوم بنسخ قطع كبيرة من الوثائق حول ، على سبيل المثال ، في:

يتم تكرار 4 أسطر من التعليقات. Yikes ، غير جاف.





javadoc