Thông tin về ứng dụng này
Đây là tiện ích sổ ghi nhớ của "Nhận xét thẳng thắn".
Vui lòng nhấn vào tiện ích và bạn có thể viết ghi chú trên đó.
Ứng dụng này là một tiện ích cho màn hình chính của bạn và bạn có thể cá nhân hóa nó. Tiếp tục nhấn vào màn hình chính cho đến khi một menu widget bổ sung xuất hiện. Chọn “Ghi chú ghi chú thẳng thắn” từ danh sách các vật dụng.
Hãy chơi GACHA [Đồ chơi viên nang]. Bạn sẽ nhận được các tiện ích ghi chú dễ thương.
[C] ittsukiyu
http. //twpf. jp/itsukiyu
https. //twitter. com/itsukiyu/status/704158668317528064
Cung cấp bởi ARTSPLANET
Lần cập nhật gần đây nhất
John Otander. [00. 00] Ghi chú đi kèm với giao diện dòng lệnh hoặc CLI, có thể được sử dụng để tự động hóa các tác vụ. Đầu tiên, chỉ cần tiếp tục và kiểm tra tài liệu. Tùy chọn kiểm tra đăng xuất toàn bộ AST, có thể được sử dụng để gỡ lỗi plugin
[00. 15] Như chúng ta cũng thấy ở đây, chúng ta có tiêu đề "Mục lục" và không có phần con nào bên dưới nó. Chúng tôi có thể tự động điền thông tin này bằng cách sử dụng plugin nhận xét toc như một phần của lệnh CLI. Bây giờ mục lục đã được điền
[00. 29] Tuy nhiên, nếu bạn chạy lệnh kiểm tra một lần nữa, chúng ta sẽ thấy mục lục không được duy trì. Đó là bởi vì chúng tôi đã không chỉ định đầu ra
[00. 37] Với các tùy chọn đầu ra được chỉ định, giờ đây chúng ta có thể kiểm tra thêm một lần nữa và thấy rằng nó đã được điền. Ngoài các plugin điều khiển đánh dấu của bạn, bạn cũng có thể sử dụng các plugin để linting
[00. 48] Ở đây, chúng tôi sẽ chống lại hướng dẫn phong cách đánh dấu của chúng tôi. Khi chúng tôi chạy lệnh, chúng tôi sẽ thấy một danh sách các lỗi đã được tạo dựa trên tùy chọn của chúng tôi. Ngoài ra, chúng tôi có thể chạy các lệnh dựa trên việc linting đã thành công hay thất bại. Mặc dù để điều này hoạt động, chúng tôi sẽ phải chỉ định tùy chọn yếu, điều đó có nghĩa là nó sẽ báo lỗi. Điều này dẫn đến việc chúng tôi thấy thất bại hơn là vượt qua
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 các trang tham khảo Javadoc
- Để 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
- Nguyên tắc
- Thuật ngữ
- Tệp nguồn
- Viết bình luận tài liệu
- Định dạng của một Doc Comment
- Công cụ kiểm tra bình luận tài liệu
- mô tả
- Hướng dẫn về phong cách
- Quy ước về thẻ [
1]/** * This is a simulation of Prof. Knuth's MIX computer. */ - Tài liệu Trình xây dựng mặc định
- Tài liệu ngoại lệ với thẻ @throws
- Nhận xét cấp gói
- Ghi lại các lớp bên trong ẩn danh
- Bao gồm hình ảnh
- Ví dụ về Doc Comments
- Khắc phục sự cố Trích dẫn xoăn [Microsoft Word]
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 điề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 về cách ghi lại sự khác biệt trong việc triển khai tài liệu một cách nổi bật
Đặ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ác thẻ tùy chỉnh, đượ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 [chẳng hạn như
/**
* 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ả ở trên. 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. Tệp nguồn
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ú
- HTML kết quả từ việc chạy Javadoc đượ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 [
00]/** * This is a simulation of Prof. Knuth's MIX computer. */ - Bắt đầu với Javadoc 1. 4, các dấu hoa thị hàng đầu là tùy chọn
- 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
01, 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 đ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
02, 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 [
03] 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í dụ đơn giản
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
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
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.
*/
Ngoài ra, hãy xem Khắc phục sự cố Dấu ngoặc kép xoăn [Microsoft Word] ở 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 " và tóm tắt gói. html là tệp mà công cụ Javadoc tạo ra
Công cụ Javadoc xử lý
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
- Sao chép nội dung của nó [mọi thứ từ
417 đến/** * This is a simulation of Prof. Knuth's MIX computer. */
418] bên dưới bảng tóm tắt trong tệp đích/** * This is a simulation of Prof. Knuth's MIX computer. */
419/** * This is a simulation of Prof. Knuth's MIX computer. */ - Xử lý bất kỳ thẻ Javadoc
9,/** * This is a simulation of Prof. Knuth's MIX computer. */
34 hoặc/** * This is a simulation of Prof. Knuth's MIX computer. */
63 nào hiện có/** * This is a simulation of Prof. Knuth's MIX computer. */ - Sao chép câu đầu tiên vào cột bên phải của Tổng quan Tóm tắt
Mẫu cho gói. tệp nguồn html
Tại Oracle, chúng tôi sử dụng mẫu sau, Mẫu trống cho tệp nhận xét tài liệu cấp gói, khi tạo tệp nhận xét tài liệu gói mới. Điều này chứa một tuyên bố bản quyền. Rõ ràng, nếu bạn đến từ một công ty khác, bạn sẽ cung cấp tuyên bố bản quyền của riêng mình. Một kỹ sư sẽ sao chép toàn bộ tệp này, đổi tên thành
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
nội dung của gói. tệp nguồn html
Nhận xét tài liệu gói phải cung cấp [trực tiếp hoặc qua liên kết] mọi thứ cần thiết để cho phép lập trình viên sử dụng gói. Nó là một phần rất quan trọng của tài liệu. đối với nhiều cơ sở [những cơ sở nằm trong một gói nhưng không nằm trong một lớp đơn lẻ], đây là nơi đầu tiên mà các lập trình viên sẽ tìm kiếm tài liệu. Nó phải chứa một mô tả ngắn gọn, dễ đọc về các tiện ích được cung cấp bởi gói [trong phần giới thiệu, bên dưới] theo sau là các chỉ dẫn đến tài liệu chi tiết hoặc bản thân tài liệu chi tiết, tùy theo điều kiện nào phù hợp. Cái nào phù hợp sẽ phụ thuộc vào gói. một con trỏ phù hợp nếu nó là một phần của hệ thống lớn hơn [chẳng hạn như một trong 37 gói trong Corba] hoặc nếu tài liệu Framemaker đã tồn tại cho gói đó;
Tóm lại, mục đích chính của nhận xét về tài liệu gói là để mô tả mục đích của gói, khung khái niệm cần thiết để hiểu và sử dụng nó cũng như mối quan hệ giữa các lớp cấu thành nó. Đối với các gói lớn, phức tạp [và những gói là một phần của API lớn, phức tạp], con trỏ tới tài liệu kiến trúc bên ngoài được đảm bảo
Sau đây là các phần và tiêu đề bạn nên sử dụng khi viết tệp nhận xét cấp gói. Không nên có tiêu đề trước câu đầu tiên, vì công cụ Javadoc lấy văn bản đầu tiên làm câu tóm tắt
- Làm cho câu đầu tiên là một bản tóm tắt của gói. Ví dụ. "Cung cấp các lớp và giao diện để xử lý văn bản, ngày tháng, số và tin nhắn theo cách độc lập với ngôn ngữ tự nhiên. "
- Mô tả những gì gói chứa và nêu rõ mục đích của nó
- Đặc điểm kỹ thuật gói
- Bao gồm mô tả hoặc liên kết đến bất kỳ thông số kỹ thuật nào trên toàn bộ gói cho gói này không có trong phần còn lại của tài liệu do javadoc tạo. Ví dụ, java. gói awt có thể mô tả cách hành vi chung trong gói đó được phép thay đổi từ hệ điều hành này sang hệ điều hành khác [Windows, Solaris, Mac]
- Bao gồm các liên kết đến bất kỳ thông số kỹ thuật nào được viết bên ngoài các nhận xét tài liệu [chẳng hạn như trong FrameMaker hoặc bất kỳ thứ gì] nếu chúng chứa các xác nhận không có trong các tệp do javadoc tạo
- Bao gồm các tài liệu tham khảo cụ thể. Nếu chỉ một phần của tài liệu được tham chiếu được coi là một phần của thông số kỹ thuật API, thì bạn nên liên kết hoặc chỉ tham chiếu đến phần đó và tham khảo phần còn lại của tài liệu trong phần tiếp theo. Ý tưởng là phân định rõ ràng đâu là một phần của thông số kỹ thuật API và đâu là không, để nhóm JCK có thể viết các bài kiểm tra với phạm vi phù hợp. Điều này thậm chí có thể khuyến khích một số người viết chia nhỏ các tài liệu để thông số kỹ thuật được tách biệt
Một xác nhận là một tuyên bố mà người triển khai tuân thủ sẽ phải biết để triển khai nền tảng Java
Trên cơ sở đó, tại Oracle, các tài liệu tham khảo trong phần này rất quan trọng đối với Bộ công cụ tương thích Java [JCK]. Bộ công cụ tương thích Java bao gồm một bài kiểm tra để xác minh từng xác nhận, để xác định những gì được coi là Tương thích với Java. Câu lệnh "Trả về một int" là một khẳng định. Một ví dụ không phải là một khẳng định
Một số "thông số kỹ thuật" mà các kỹ sư đã viết không chứa xác nhận nào chưa được nêu trong thông số kỹ thuật API [javadoc] -- chúng chỉ giải thích chi tiết về thông số kỹ thuật API. Về mặt này, một tài liệu như vậy không nên được đề cập trong phần này, mà nên được đề cập trong phần tiếp theo
- Tài liệu liên quan
- Bao gồm các tham chiếu đến bất kỳ tài liệu nào không chứa xác nhận đặc điểm kỹ thuật, chẳng hạn như tổng quan, hướng dẫn, ví dụ, trình diễn và hướng dẫn
- Tóm tắt lớp và giao diện
- [Bỏ qua phần này cho đến khi chúng tôi triển khai thẻ @category]
- Mô tả các nhóm logic của các lớp và giao diện
9 các gói, lớp và giao diện khác/** * This is a simulation of Prof. Knuth's MIX computer. */
Ghi lại các lớp bên trong ẩn danh
Các lớp bên trong ẩn danh được định nghĩa trong Đặc tả ngôn ngữ Java, Phiên bản thứ hai, tại Tuyên bố lớp ẩn danh. Công cụ Javadoc không ghi lại trực tiếp các lớp ẩn danh -- nghĩa là các khai báo và nhận xét về tài liệu của chúng bị bỏ qua. Nếu bạn muốn ghi lại một lớp ẩn danh, cách thích hợp để làm như vậy là trong một nhận xét tài liệu về lớp bên ngoài của lớp đó hoặc một lớp liên quan chặt chẽ khác
Ví dụ: nếu bạn có một lớp bên trong
/**
* 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.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Bao gồm hình ảnh
Phần này bao gồm các hình ảnh được sử dụng trong các nhận xét tài liệu, không phải hình ảnh được sử dụng trực tiếp bởi mã nguồn
GHI CHÚ. Hình ảnh đầu dòng và tiêu đề cần có với Javadoc phiên bản 1. 0 và 1. 1 nằm trong thư mục hình ảnh của gói tải xuống JDK.
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Trước Javadoc 1. 2, công cụ Javadoc sẽ không sao chép hình ảnh vào thư mục đích -- bạn phải thực hiện việc đó trong một thao tác riêng, thủ công hoặc bằng tập lệnh. Javadoc 1. 2 tìm kiếm và sao chép vào thư mục đích một thư mục có tên "doc-files" trong cây nguồn [một thư mục cho mỗi gói] và nội dung của nó. [Nó thực hiện một bản sao nông cho 1. 2 và 1. 3 và một bản sao sâu cho 1. 4 trở lên. ] Vì vậy, bạn có thể đưa vào thư mục này bất kỳ hình ảnh nào [GIF, JPEG, v.v.] hoặc các tệp khác không được xử lý bằng công cụ Javadoc
Sau đây là các đề xuất Phần mềm Java cho các quy ước bao gồm hình ảnh trong nhận xét tài liệu. Các hình ảnh chính sẽ được đặt trong cây nguồn;
Hình ảnh trong cây nguồn
- Đặt tên ảnh doc trong cây nguồn - Đặt tên ảnh GIF
433, tăng số nguyên cho các ảnh tiếp theo cùng lớp. Thí dụ/** * This is a simulation of Prof. Knuth's MIX computer. */
434/** * This is a simulation of Prof. Knuth's MIX computer. */ - Vị trí của hình ảnh tài liệu trong cây nguồn - Đặt hình ảnh tài liệu trong thư mục có tên là "tệp tài liệu". Thư mục này phải nằm trong cùng thư mục gói nơi chứa các tệp nguồn. [Tên "tệp tài liệu" phân biệt nó là tài liệu tách biệt với hình ảnh được sử dụng bởi chính mã nguồn, chẳng hạn như ảnh bitmap được hiển thị trong GUI. ] Thí dụ. Ảnh chụp màn hình của một nút,
434, có thể được đưa vào nhận xét lớp cho lớp Nút. Tệp nguồn Nút và hình ảnh sẽ được đặt tại/** * This is a simulation of Prof. Knuth's MIX computer. */
436 [tệp nguồn]/** * This is a simulation of Prof. Knuth's MIX computer. */
437 [tệp hình ảnh]/** * This is a simulation of Prof. Knuth's MIX computer. */
Hình ảnh trong đích HTML
- Đặt tên cho hình ảnh tài liệu ở đích HTML - Hình ảnh sẽ có cùng tên như trong cây nguồn. Thí dụ
434/** * This is a simulation of Prof. Knuth's MIX computer. */ - Vị trí của hình ảnh tài liệu trong đích HTML
- Với đầu ra tệp phân cấp, chẳng hạn như Javadoc 1. 2, các thư mục sẽ được đặt trong thư mục gói có tên "doc-files". Ví dụ
439/** * This is a simulation of Prof. Knuth's MIX computer. */ With flat file output, such as Javadoc 1.1, directories would be located in the package directory and named "images-". For example:
49/** * This is a simulation of Prof. Knuth's MIX computer. */
- Với đầu ra tệp phân cấp, chẳng hạn như Javadoc 1. 2, các thư mục sẽ được đặt trong thư mục gói có tên "doc-files". Ví dụ
Ví dụ về Doc Comments
/**
* This is a simulation of Prof. Knuth's MIX computer.
*/
Khắc phục sự cố Trích dẫn xoăn [Microsoft Word]
Sự cố - Xảy ra sự cố nếu bạn đang làm việc trong một trình soạn thảo mặc định là dấu ngoặc đơn và dấu ngoặc kép cong [chứ không phải thẳng], chẳng hạn như Microsoft Word trên PC -- dấu ngoặc kép biến mất khi được hiển thị trong một số trình duyệt [chẳng hạn như Unix Netscape]. Vì vậy, một cụm từ như "đặc điểm của màn hình" trở thành "đặc điểm của màn hình. "
Các ký tự không hợp lệ như sau
- 146 - trích dẫn đơn bên phải
- 147 - trích dẫn kép bên trái
- 148 - trích dẫn kép bên phải
Những gì nên được sử dụng thay thế là
- 39 - trích dẫn đơn
- 34 - trích dẫn thẳng
Giải pháp phòng ngừa - Lý do xảy ra trích dẫn "bất hợp pháp" là tùy chọn Word mặc định là "Thay đổi 'Trích dẫn thẳng' thành 'Trích dẫn thông minh'". Nếu bạn tắt tính năng này, bạn sẽ nhận được dấu ngoặc kép thích hợp khi nhập
Sửa các trích dẫn quăn - Microsoft Word có một số tùy chọn lưu -- sử dụng "Chỉ lưu dưới dạng văn bản" để thay đổi các trích dẫn trở lại thành các trích dẫn thẳng. Đảm bảo sử dụng đúng tùy chọn
- "Chỉ lưu dưới dạng văn bản với ngắt dòng" - chèn khoảng trắng ở cuối mỗi dòng và giữ dấu ngoặc kép
- "Chỉ lưu dưới dạng văn bản" - không chèn khoảng trắng ở cuối mỗi dòng và thay đổi dấu nháy cong thành dấu nháy thẳng
chú thích
[1] Tại Phần mềm Java, chúng tôi sử dụng @version cho phiên bản SCCS. Xem "man sccs-get" để biết chi tiết. Sự đồng thuận dường như là như sau
%I% được tăng lên mỗi khi bạn chỉnh sửa và xóa tệp
%G% là ngày mm/dd/yy
Khi bạn tạo một tệp, %I% được đặt thành 1. 1. Khi bạn chỉnh sửa và xóa nó, nó sẽ tăng lên 1. 2
Một số nhà phát triển bỏ qua ngày %G% [và đã và đang làm như vậy] nếu họ thấy nó quá khó hiểu -- ví dụ: 4/3/96, mà %G% sẽ tạo ra cho ngày 4 tháng 3, sẽ được giải thích bởi những người bên ngoài Hoa Kỳ . Một số nhà phát triển chỉ bao gồm thời gian %U% nếu họ muốn độ phân giải tốt hơn [do có nhiều lần đăng ký trong một ngày]
Định dạng ngày tháng dạng số rõ ràng nhất sẽ có ngày được định dạng theo năm đầu tiên, chẳng hạn như yyyy-mm-dd, như được đề xuất trong ISO 8601 và các nơi khác [chẳng hạn như http. //www. cl. cam. AC. uk/~mgk25/iso-time. html], nhưng cải tiến đó cần đến từ SCCS