Chương này cung cấp tổng quan về cú pháp của "DocBlocks". Tác dụng chính xác của thẻ bao gồm các ví dụ được cung cấp trong các chương khác nhau có thể truy cập được qua tài liệu này
Nội dung chính Hiển thị
- Cú pháp cơ bản
- DocBlock là gì?
- Những phần tử nào có thể có DocBlock
- Sự mô tả
- Di sản
- Nhận xét PHPDoc là gì?
- Làm thế nào để bạn ghi lại mã PHP?
- Phần tử nào sau đây có thể được ghi lại bằng PhpDocumentor?
- Tôi làm cách nào để chạy PhpDocumentor?
DocBlock là gì?
DocBlock là một loại nhận xét đặc biệt có thể cung cấp thông tin chi tiết về một thành phần trong mã của bạn
Thông tin được cung cấp trong loại nhận xét này có thể được các nhà phát triển sử dụng để hiểu về chức năng của một phần tử nhất định;
Đây là một ví dụ về DocBlock vì nó có thể gặp phải
/**
* This is the summary for a DocBlock.
*
* This is the description for a DocBlock. This text may contain
* multiple lines and even some _markdown_.
*
* * Markdown style lists function too
* * Just try this out once
*
* The section after the description contains the tags; which provide
* structured meta-data concerning the given element.
*
* @author Mike van Riel
*
* @since 1.0
*
* @param int $example This is an example function/method parameter description.
* @param string $example2 This is a second example.
*/
Những phần tử nào có thể có DocBlock
Tất cả các phần tử cấu trúc đều có thể được đặt trước bởi DocBlock. Các yếu tố sau đây được tính như vậy
yêu cầu [_once] bao gồm [_once] chức năng đặc điểm giao diện lớp [bao gồm các phương thức] hằng số thuộc tính * biến, cả phạm vi cục bộ và toàn cục
phần
Một DocBlock đại khái tồn tại gồm 3 phần
- Bản tóm tắt;
- Sự mô tả;
- Thẻ;
Bản tóm tắt
Phần tóm tắt được sử dụng để tạo ấn tượng về chức năng của phần tử được ghi lại. Điều này có thể được sử dụng trong phần tổng quan để cho phép người dùng đọc lướt tài liệu để tìm kiếm mẫu được yêu cầu
Tóm tắt phải luôn kết thúc bằng dấu chấm hoặc 2 dòng mới liên tiếp. Nếu nó không được đóng lại như thế này thì mọi mô tả sẽ được coi là một phần của bản tóm tắt
Tóm tắt sẽ là văn bản thuần túy. Không giống như các thành phần văn bản khác trong DocBlocks Markdown không được hỗ trợ, cũng như các thẻ
A full stop means that the dot [`.`] needs to be succeeded by a new line. This way it is possible to mention
abbreviations as "e.g.", version numbers or other texts containing dots without ending the summary.
Sự mô tả
Mô tả chứa thông tin ngắn gọn về chức năng của phần tử tài liệu. Được phép và khuyến khích sử dụng đánh dấu Markdown để áp dụng kiểu dáng
Danh sách sau đây có ví dụ về các loại thông tin có thể chứa trong mô tả
- Giải thích thuật toán
- Ví dụ về mã
- Đặc tả mảng
- Mối quan hệ với các yếu tố khác
- Thông tin giấy phép [trong trường hợp tệp DocBlocks]
Mô tả cũng có thể chứa các thẻ nội tuyến. Đây là những chú thích đặc biệt có thể thay thế cho một loại thông tin chuyên biệt [chẳng hạn như {@link}]. Các thẻ nội tuyến luôn được bao quanh bởi dấu ngoặc nhọn
Một danh sách đầy đủ được cung cấp trong tài liệu tham khảo thẻ nội tuyến
Di sản
Docblocks tự động kế thừa Tóm tắt và Mô tả của phần tử được ghi đè, mở rộng hoặc triển khai
Ví dụ. nếu Lớp B mở rộng Lớp A và nó có một DocBlock trống được xác định, thì nó sẽ có cùng Tóm tắt và Mô tả như Lớp A. Không có DocBlock nghĩa là DocBlock 'cha' sẽ không bị ghi đè và sẽ xảy ra lỗi trong quá trình phân tích cú pháp
Hình thức kế thừa này áp dụng cho bất kỳ phần tử nào có thể bị ghi đè, chẳng hạn như Lớp, Giao diện, Phương thức và Thuộc tính. Các hằng số và hàm không thể bị ghi đè và do đó không có hành vi này
Xin lưu ý rằng bạn cũng có thể bổ sung Mô tả bằng Mô tả của cha mẹ bằng cách sử dụng thẻ nội tuyến {@inheritdoc}
Mỗi phần tử cũng kế thừa một bộ thẻ cụ thể;
Những điều sau đây áp dụng
Các phần tửThẻ kế thừaBất kỳ. tài liệu. `thẻ/tác giả`,. tài liệu. `thẻ/phiên bản`,. tài liệu. `tags/copyright`Lớp và Giao diện. tài liệu. `thẻ/danh mục`,. tài liệu. `thẻ/gói`,. tài liệu. `thẻ/gói phụ`Phương thức. tài liệu. `thẻ/tham số`,. tài liệu. `thẻ/trả lại`,. tài liệu. `thẻ/ném`Thuộc tính. tài liệu. `thẻ/var`Xin lưu ý rằng các thẻ @subpackage chỉ được kế thừa nếu lớp cha có cùng @package. Mặt khác, người ta cho rằng lớp cha là một phần của thư viện có thể có cấu trúc khác
Nhận xét PHPDoc là gì?
khối phpDoc là nhận xét mô tả là một phần của mã ứng dụng . Chúng được sử dụng để mô tả phần tử PHP ở vị trí chính xác trong mã nơi phần tử xuất hiện. Khối bao gồm một mô tả ngắn, mô tả dài và các thẻ phpDoc.
Làm thế nào để bạn ghi lại mã PHP?
Ghi lại đúng mã PHP .
Các lớp học. Bắt đầu mọi lớp học với /** * Mô tả lớp học * * @author Tên tổ chức hoặc cá nhân của bạn * @license MIT [hoặc giấy phép khác] */
Đặc tính. Ghi lại mọi thuộc tính với /** * Mô tả ngắn gọn về thuộc tính * * @var type */
phương pháp. .
Phần tử nào sau đây có thể được ghi lại bằng PhpDocumentor?
phpDocumentor có khả năng tự động ghi lại các câu lệnh bao gồm , định nghĩa câu lệnh, hàm, trang thủ tục, lớp, biến lớp và phương thức lớp .
Tôi làm cách nào để chạy PhpDocumentor?
Tất cả những gì bạn cần làm là thêm tệp có tên 'phpdoc. dist. xml' vào thư mục gốc của dự án, thêm các tùy chọn của bạn vào đó rồi gọi lệnh phpdoc mà không cần đối số