Tài liệu này mô tả các quy ước hướng dẫn về phong cách, thẻ và hình ảnh mà chúng tôi sử dụng trong các nhận xét tài liệu cho các chương trình Java được viết tại Phần mềm Java, Oracle. Nó không làm lại tài liệu liên quan được đề cập ở nơi khác
- Để biết tài liệu tham khảo về các thẻ Javadoc, hãy xem
- Để biết nội dung ngữ nghĩa cần thiết của các nhận xét tài liệu, hãy xem Yêu cầu để viết Thông số kỹ thuật API Java
nội dung
- Giới thiệu
- Viết bình luận tài liệu
- [
1]/** * This is a simulation of Prof. Knuth's MIX computer. */
- [
Giới thiệu
Nguyên tắc
Tại Phần mềm Java, chúng tôi có một số nguyên tắc có thể làm cho nhận xét tài liệu của chúng tôi khác với nhận xét của các nhà phát triển bên thứ ba. Nhận xét tài liệu của chúng tôi xác định Đặc tả API nền tảng Java chính thức. Để đạt được mục tiêu này, đối tượng mục tiêu của chúng tôi là những người viết các bài kiểm tra khả năng tương thích Java, hoặc tuân thủ hoặc triển khai lại nền tảng Java, ngoài các nhà phát triển. Chúng tôi dành thời gian và nỗ lực tập trung vào việc chỉ định các điều kiện biên, phạm vi đối số và trường hợp góc hơn là xác định các thuật ngữ lập trình phổ biến, viết tổng quan về khái niệm và bao gồm các ví dụ cho nhà phát triển
Do đó, thường có hai cách khác nhau để viết nhận xét tài liệu -- dưới dạng thông số API hoặc dưới dạng tài liệu hướng dẫn lập trình. Hai mục tiêu này được mô tả trong các phần sau. Một nhân viên có nguồn lực dồi dào có thể đủ khả năng để kết hợp cả hai vào cùng một tài liệu ["chunked" đúng cách]; . Đây là lý do tại sao các nhà phát triển thường cần chuyển sang các tài liệu khác, chẳng hạn như Tài liệu kỹ thuật Java SE và Hướng dẫn Java để biết hướng dẫn lập trình
Viết thông số kỹ thuật API
Lý tưởng nhất là Đặc tả API Java bao gồm tất cả các xác nhận cần thiết để thực hiện triển khai trong phòng sạch của Nền tảng Java để "viết một lần, chạy mọi nơi" -- sao cho mọi ứng dụng hoặc ứng dụng Java sẽ chạy giống nhau trên mọi triển khai. Điều này có thể bao gồm các xác nhận trong các nhận xét tài liệu cộng với các xác nhận trong bất kỳ thông số kỹ thuật kiến trúc và chức năng nào [thường được viết bằng FrameMaker] hoặc trong bất kỳ tài liệu nào khác. Định nghĩa này là một mục tiêu cao cả và có một số hạn chế thực tế đối với mức độ đầy đủ mà chúng tôi có thể chỉ định API. Sau đây là các nguyên tắc hướng dẫn mà chúng tôi cố gắng tuân theo
Đặc tả API nền tảng Java được xác định bởi các nhận xét tài liệu trong mã nguồn và bất kỳ tài liệu nào được đánh dấu là thông số kỹ thuật có thể truy cập được từ các nhận xét đó
Lưu ý rằng thông số kỹ thuật không cần phải được chứa hoàn toàn trong tài liệu bình luận. Đặc biệt, các thông số kỹ thuật dài đôi khi được định dạng tốt nhất trong một tệp riêng biệt và được liên kết từ nhận xét tài liệu
Đặc tả API nền tảng Java là hợp đồng giữa người gọi và triển khai
Đặc tả mô tả tất cả các khía cạnh của hành vi của từng phương thức mà người gọi có thể dựa vào. Nó không mô tả chi tiết triển khai, chẳng hạn như phương thức này là gốc hay được đồng bộ hóa. Thông số kỹ thuật phải mô tả [bằng văn bản] các đảm bảo an toàn luồng được cung cấp bởi một đối tượng nhất định. Trong trường hợp không có chỉ dẫn rõ ràng ngược lại, tất cả các đối tượng được coi là "an toàn luồng" [i. e. , cho phép nhiều luồng truy cập đồng thời]. Người ta nhận ra rằng các thông số kỹ thuật hiện tại không phải lúc nào cũng phù hợp với lý tưởng này
Trừ khi có ghi chú khác, các xác nhận Đặc tả API Java cần phải độc lập với việc triển khai. Các trường hợp ngoại lệ phải được tách biệt và đánh dấu nổi bật như vậy
Chúng tôi có hướng dẫn cho
Đặc tả API Java phải chứa các xác nhận đủ để cho phép Đảm bảo chất lượng phần mềm viết các bài kiểm tra Bộ công cụ tương thích Java [JCK] hoàn chỉnh
Điều này có nghĩa là các nhận xét tài liệu phải đáp ứng nhu cầu kiểm tra sự phù hợp của SQA. Các nhận xét không nên ghi lại lỗi hoặc cách triển khai hiện không có thông số kỹ thuật sẽ hoạt động
Viết tài liệu hướng dẫn lập trình
Điều khác biệt giữa các đặc tả API với hướng dẫn lập trình là các ví dụ, định nghĩa về các thuật ngữ lập trình phổ biến, tổng quan khái niệm nhất định [chẳng hạn như ẩn dụ] và mô tả về các lỗi triển khai và cách giải quyết. Không có tranh cãi rằng những điều này góp phần vào sự hiểu biết của nhà phát triển và giúp nhà phát triển viết các ứng dụng đáng tin cậy nhanh hơn. Tuy nhiên, vì chúng không chứa "xác nhận" API nên chúng không cần thiết trong đặc tả API. Bạn có thể bao gồm bất kỳ hoặc tất cả thông tin này trong nhận xét tài liệu [và có thể bao gồm , được xử lý bởi một tài liệu tùy chỉnh, để tạo điều kiện thuận lợi]. Tại Phần mềm Java, chúng tôi cố ý không đưa mức tài liệu này vào các nhận xét về tài liệu và thay vào đó, chúng tôi đưa các liên kết đến thông tin này [liên kết đến Hướng dẫn Java và danh sách các thay đổi] hoặc đưa thông tin này vào gói tải xuống tài liệu tương tự như thông số kỹ thuật API
Thật hữu ích khi đi vào chi tiết hơn về cách ghi lại các lỗi và cách giải quyết. Đôi khi có sự khác biệt giữa cách mã hoạt động và cách nó thực sự hoạt động. Điều này có thể có hai hình thức khác nhau. Lỗi đặc tả API và lỗi mã. Thật hữu ích khi quyết định trước xem bạn có muốn ghi lại những điều này trong các nhận xét về tài liệu hay không. Tại Phần mềm Java, chúng tôi đã quyết định ghi lại cả hai điều này bên ngoài nhận xét tài liệu, mặc dù chúng tôi có ngoại lệ
Lỗi đặc tả API là lỗi xuất hiện trong khai báo phương thức hoặc trong nhận xét tài liệu ảnh hưởng đến cú pháp hoặc ngữ nghĩa. Một ví dụ về lỗi đặc tả như vậy là một phương thức được chỉ định để đưa ra một NullPulumException khi
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Lỗi mã là lỗi trong quá trình triển khai chứ không phải trong đặc tả API. Lỗi mã và cách giải quyết của chúng cũng thường được phân phối riêng trong báo cáo lỗi. Tuy nhiên, nếu công cụ Javadoc đang được sử dụng để tạo tài liệu cho một triển khai cụ thể, sẽ rất hữu ích nếu đưa thông tin này vào các nhận xét về tài liệu, được phân tách phù hợp dưới dạng ghi chú hoặc bằng thẻ tùy chỉnh [giả sử
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Ai sở hữu và chỉnh sửa Tài liệu Nhận xét
Các nhận xét tài liệu cho đặc tả API nền tảng Java thuộc sở hữu của các lập trình viên. Tuy nhiên, chúng được chỉnh sửa bởi cả người lập trình và người viết. Đó là tiền đề cơ bản mà các nhà văn và lập trình viên tôn vinh khả năng của nhau và cả hai đều đóng góp vào các nhận xét tài liệu tốt nhất có thể. Thông thường, vấn đề là đàm phán để xác định ai viết phần nào của tài liệu, dựa trên kiến thức, thời gian, tài nguyên, sở thích, độ phức tạp của API và trạng thái của chính việc triển khai. Nhưng các ý kiến cuối cùng phải được sự đồng ý của kỹ sư chịu trách nhiệm
Lý tưởng nhất là người thiết kế API sẽ viết đặc tả API trong các tệp nguồn khung, chỉ có khai báo và nhận xét tài liệu, chỉ điền vào phần triển khai để đáp ứng hợp đồng API đã viết. Mục đích của người viết API là giúp người thiết kế bớt một số công việc này. Trong trường hợp này, nhà thiết kế API sẽ viết nhận xét tài liệu ban đầu bằng ngôn ngữ thưa thớt, sau đó người viết sẽ xem xét nhận xét, tinh chỉnh nội dung và thêm thẻ
Nếu nhận xét về tài liệu là một đặc tả API dành cho người triển khai lại và không chỉ đơn giản là hướng dẫn dành cho nhà phát triển, thì chúng phải được viết bởi lập trình viên đã thiết kế và triển khai API hoặc bởi người viết API đã hoặc đã trở thành chuyên gia về chủ đề. Nếu việc triển khai được ghi vào thông số kỹ thuật nhưng các nhận xét về tài liệu chưa hoàn thành, người viết có thể hoàn thành các nhận xét về tài liệu bằng cách kiểm tra mã nguồn hoặc viết các chương trình kiểm tra API. Người viết có thể kiểm tra hoặc kiểm tra các ngoại lệ được đưa ra, các điều kiện biên của tham số và để chấp nhận các đối số null. Tuy nhiên, một tình huống khó khăn hơn nhiều phát sinh nếu việc triển khai không được ghi vào thông số kỹ thuật. Sau đó, người viết chỉ có thể tiến hành viết đặc tả API nếu họ biết ý định của nhà thiết kế [thông qua các cuộc họp thiết kế hoặc thông qua đặc tả thiết kế được viết riêng] hoặc có quyền truy cập sẵn sàng với nhà thiết kế để đặt câu hỏi của họ. Do đó, người viết có thể gặp khó khăn hơn khi viết tài liệu cho các giao diện và lớp trừu tượng không có trình triển khai
Với ý nghĩ đó, những hướng dẫn này nhằm mô tả các nhận xét về tài liệu đã hoàn thành. Chúng nhằm mục đích gợi ý chứ không phải là yêu cầu phải tuân theo một cách mù quáng nếu chúng có vẻ quá nặng nề hoặc nếu có thể tìm thấy các giải pháp thay thế sáng tạo. Khi một hệ thống phức tạp như Java [chứa khoảng 60 gói] đang được phát triển, thường thì một nhóm kỹ sư đóng góp cho một bộ gói cụ thể, chẳng hạn như
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Thuật ngữ
Tài liệu API [API docs] hay thông số API [API specs]
Mô tả trực tuyến hoặc bản cứng của API, chủ yếu dành cho các lập trình viên viết bằng Java. Chúng có thể được tạo bằng công cụ Javadoc hoặc được tạo theo một số cách khác. Đặc tả API là một loại tài liệu API cụ thể, như được mô tả. Một ví dụ về đặc tả API là Nền tảng Java trực tuyến, Đặc tả API Standard Edition 7
Bình luận tài liệu [bình luận tài liệu]
Các chú thích đặc biệt trong mã nguồn Java được phân cách bằng dấu phân cách
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
javadoc
Công cụ JDK tạo tài liệu API từ nhận xét tài liệu
Tệp nguồn
Công cụ Javadoc có thể tạo đầu ra bắt nguồn từ bốn loại tệp "nguồn" khác nhau
- Các tệp mã nguồn cho các lớp Java [. java] - chúng chứa các nhận xét về lớp, giao diện, trường, hàm tạo và phương thức
- Các tệp nhận xét gói - những tệp này chứa các nhận xét gói
- Các tệp nhận xét tổng quan - những tệp này chứa các nhận xét về tập hợp các gói
- Các tệp chưa xử lý khác - bao gồm hình ảnh, mã nguồn mẫu, tệp lớp, applet, tệp HTML và bất kỳ thứ gì khác mà bạn có thể muốn tham khảo từ các tệp trước đó
Để biết thêm chi tiết, xem.
Viết bình luận tài liệu
Định dạng của một Doc Comment
Một nhận xét tài liệu được viết bằng HTML và phải đứng trước một khai báo lớp, trường, hàm tạo hoặc phương thức. Nó bao gồm hai phần -- một mô tả theo sau bởi các thẻ khối. Trong ví dụ này, các thẻ khối là
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
*
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage[URL url, String name] {
try {
return getImage[new URL[url, name]];
} catch [MalformedURLException e] {
return null;
}
}
ghi chú
- Javadoc đang chạy được hiển thị bên dưới
- Mỗi dòng ở trên được thụt vào để căn chỉnh với mã bên dưới nhận xét
- Dòng đầu tiên chứa dấu phân cách bắt đầu nhận xét [
0]/** * This is a simulation of Prof. Knuth's MIX computer. */ - Bắt đầu với Javadoc 1. 4, các
- Viết câu đầu tiên dưới dạng tóm tắt ngắn về phương thức, vì Javadoc sẽ tự động đặt câu đó vào bảng tóm tắt phương thức [và chỉ mục]
- Lưu ý thẻ nội tuyến
1, thẻ này chuyển đổi thành siêu liên kết HTML trỏ đến tài liệu cho lớp URL. Thẻ nội tuyến này có thể được sử dụng ở bất cứ nơi nào có thể viết nhận xét, chẳng hạn như trong văn bản theo sau thẻ khối/** * This is a simulation of Prof. Knuth's MIX computer. */ - Nếu bạn có nhiều hơn một đoạn văn trong nhận xét tài liệu, hãy tách các đoạn văn bằng thẻ đoạn văn
2, như được hiển thị/** * This is a simulation of Prof. Knuth's MIX computer. */ - Chèn một dòng chú thích trống giữa mô tả và danh sách các thẻ, như được hiển thị
- Dòng đầu tiên bắt đầu bằng ký tự "@" kết thúc phần mô tả. Chỉ có một khối mô tả cho mỗi nhận xét tài liệu;
- Dòng cuối cùng chứa dấu phân cách nhận xét cuối [
3] Lưu ý rằng không giống như dấu phân cách bắt đầu nhận xét, nhận xét cuối chỉ chứa một dấu hoa thị/** * This is a simulation of Prof. Knuth's MIX computer. */
Để biết thêm ví dụ, xem
Vì vậy, các dòng sẽ không ngắt dòng, giới hạn mọi dòng nhận xét tài liệu ở 80 ký tự
Đây là ví dụ trước trông như thế nào sau khi chạy công cụ Javadoc
Lấy hình
public Image getImage[URL url,
String name]
Trả về một đối tượng
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Phương thức này luôn trả về ngay lập tức, cho dù hình ảnh có tồn tại hay không. Khi applet này cố gắng vẽ hình ảnh trên màn hình, dữ liệu sẽ được tải. Các nguyên mẫu đồ họa vẽ hình ảnh sẽ tăng dần trên màn hình
Thông số
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
trả lại
hình ảnh tại URL được chỉ định
Xem thêm
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Xem thêm ở cuối tài liệu này
Công cụ kiểm tra bình luận tài liệu
Tại Oracle, chúng tôi đã phát triển một công cụ để kiểm tra các nhận xét về tài liệu, được gọi là Oracle Doc Check Doclet hoặc DocCheck. Bạn chạy nó trên mã nguồn và nó tạo ra một báo cáo mô tả các lỗi kiểu và thẻ mà các nhận xét mắc phải, đồng thời đề xuất các thay đổi. Chúng tôi đã cố gắng làm cho các quy tắc của nó phù hợp với các quy tắc trong tài liệu này
DocCheck là một tài liệu Javadoc hay còn gọi là "trình cắm thêm" và do đó yêu cầu phải cài đặt công cụ Javadoc [như một phần của SDK Phiên bản Tiêu chuẩn Java 2]
mô tả
Câu đầu tiên
Câu đầu tiên của mỗi nhận xét tài liệu phải là một câu tóm tắt, chứa mô tả ngắn gọn nhưng đầy đủ về mục API. Điều này có nghĩa là câu đầu tiên của mỗi mô tả thành viên, lớp, giao diện hoặc gói. Công cụ Javadoc sao chép câu đầu tiên này vào phần tóm tắt thành viên, lớp/giao diện hoặc gói thích hợp. Điều này làm cho việc viết những câu đầu tiên sắc nét và đầy đủ thông tin có thể tự đứng vững là rất quan trọng.
Câu này kết thúc ở dấu chấm đầu tiên, theo sau là dấu kết thúc dòng, tab hoặc dòng hoặc ở thẻ đầu tiên [như được định nghĩa bên dưới]. Ví dụ: câu đầu tiên này kết thúc bằng "Prof. "
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Tuy nhiên, bạn có thể giải quyết vấn đề này bằng cách nhập siêu ký tự HTML chẳng hạn như "và" hoặc "