Tái sử dụng Javadoc cho các phương thức quá tải

Question 1

Tôi đang phát triển một API với nhiều phương thức được đặt tên giống hệt nhau chỉ khác nhau ở chữ ký, mà tôi đoán là khá phổ biến. Tất cả chúng đều làm điều tương tự, ngoại trừ việc chúng khởi tạo các giá trị khác nhau theo mặc định nếu người dùng không muốn chỉ định. Như một ví dụ dễ hiểu, hãy xem xét

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);
}

Hành động thiết yếu được thực hiện bởi tất cả các phương pháp này là giống nhau; một cái cây được trồng trong rừng. Nhiều điều quan trọng mà người dùng API của tôi cần biết về việc thêm cây giữ cho tất cả các phương pháp này.

Tốt nhất, tôi muốn viết một khối Javadoc được sử dụng bởi tất cả các phương pháp:

  /**
   * 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%.
   */

Trong trí tưởng tượng của tôi, một công cụ có thể chọn một cách kỳ diệu @params nào áp dụng cho mỗi phương thức và do đó tạo ra các tài liệu tốt cho tất cả các phương thức cùng một lúc.

Với Javadoc, nếu tôi hiểu nó một cách chính xác, tất cả những gì tôi có thể làm về cơ bản là sao chép và dán cùng một khối javadoc năm lần, chỉ với một danh sách tham số hơi khác nhau cho mỗi phương thức. Điều này nghe có vẻ rườm rà đối với tôi, và cũng khó duy trì.

Có đường nào quanh đó không? Một số phần mở rộng cho javadoc có loại hỗ trợ này? Hoặc có một lý do chính đáng tại sao điều này không được hỗ trợ mà tôi đã bỏ lỡ?

Question 2

Tôi không biết bất kỳ hỗ trợ nào, nhưng, tôi sẽ javadoc đầy đủ phương pháp với nhiều đối số nhất, và sau đó tham khảo nó trong javadoc khác như vậy. Tôi nghĩ nó đủ rõ ràng và tránh dư thừa.

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

Question 3

Tôi chỉ ghi lại phương thức "đầy đủ nhất" của bạn (trong trường hợp này addTree(int,Fruit,int)) và sau đó trong JavaDoc cho các phương thức khác tham khảo phương thức này và giải thích cách / giá trị mặc định nào được sử dụng cho các đối số không được cung cấp.

/**
 * 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 );

Question 4

Có thể không có phương pháp tiêu chuẩn tốt nào, vì ngay cả mã nguồn JDK9 cũng chỉ cần sao chép các phần lớn tài liệu xung quanh, ví dụ: tại:

4 dòng bình luận được lặp lại. Rất tiếc, không KHÔ.

Question 5

Đặt tài liệu vào giao diện, nếu bạn có thể. Các lớp triển khai giao diện sau đó sẽ kế thừa javadoc.

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

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

Trong trường hợp bạn muốn kế thừa tài liệu và thêm nội dung của riêng mình vào đó, bạn có thể sử dụng {@inheritDoc}:

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

Xem thêm: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

Bây giờ như tôi đã hiểu, đây không phải là chính xác những gì bạn muốn (bạn muốn tránh lặp lại giữa các phương thức trong cùng một lớp / giao diện). Đối với điều này, bạn có thể sử dụng @see hoặc @link, như những người khác mô tả, hoặc bạn có thể suy nghĩ về thiết kế của mình. Có thể bạn muốn tránh quá tải phương thức và thay vào đó sử dụng một phương thức duy nhất với một đối tượng tham số, như sau:

public Tree addTree(TreeParams p);

Để được sử dụng như thế này:

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

Bạn có thể muốn xem mẫu copy-mutator này tại đây:

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

Tùy thuộc vào số lượng kết hợp tham số, đây có thể là cách dễ dàng hơn và rõ ràng hơn, vì Params-Class có thể nắm bắt các giá trị mặc định và có một javadoc cho mỗi tham số.