javadoc شرح




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

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

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

أقوم بتطوير 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 نفسها خمس مرات ، مع قائمة معلمات تختلف قليلاً عن كل طريقة. هذا يبدو لي مرهقة ، ومن الصعب أيضا الحفاظ عليه.

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


أود فقط توثيق طريقة "الأكمل" (في هذه الحالة 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