Tái sử dụng Javadoc và các phương pháp quá tải

Question

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 theo chữ ký, mà tôi đoán là khá phổ biến. Tất cả đề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ụ về tiêu hóa, 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 đều giống nhau; một 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.

Lý tưởng 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ụ kỳ diệu có thể chọn các @params áp dụng đối với mỗi người trong số các phương pháp, và do đó tạo ra tài liệu tốt cho tất cả các phương pháp cùng một lúc.

Với Javadoc, nếu tôi hiểu chính xác, tất cả những gì tôi có thể làm là sao chép & dán cùng 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 pháp. Điều này nghe có vẻ cồng kềnh với tôi, và cũng rất khó để duy trì.

Có cách nào xung quanh điều đó không? Một số phần mở rộng cho javadoc có loại hỗ trợ này? Hoặc là 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ỡ?

Answer 1

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

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

Answer 2

Tôi chỉ muốn ghi lại phương pháp "tối đa" của bạn (trong trường hợp này addTree(int,Fruit,int)) và sau đó trong javadoc cho các phương pháp khác tham khảo này và giải thích làm thế nào/mà giá trị mặc định giá trị này đượ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); 

Answer 3

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

• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l417
• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464

4 dòng chú thích được lặp lại. Yikes, non-DRYness.

Answer 4

Đặt tài liệu vào giao diện, nếu có thể. Các lớp thực hiện 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 công cụ của riêng bạn để nó, 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 trong số 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ư được mô tả bởi những người khác, hoặc bạn có thể nghĩ về thiết kế của bạn.Có lẽ bạn muốn tránh quá tải phương pháp và sử dụng một phương pháp duy nhất với một đối tượng tham số thay vào đó, như vậy:

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 có một xem xét điều này mô hình sao chép mutator đâ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ố này có thể là cách dễ dàng hơn và sạch hơn, vì Params-Class có thể nắm bắt các giá trị mặc định và có javadoc cho mỗi tham số.