Tham số tùy chọn khối tài liệu PHP

Question

WordPress sử dụng lược đồ tài liệu tùy chỉnh lấy cảm hứng từ PHPDoc, một tiêu chuẩn đang phát triển để cung cấp tài liệu cho mã PHP, được duy trì bởi phpDocumentor

Tài liệu PHP trong WordPress chủ yếu ở dạng khối tài liệu được định dạng hoặc nhận xét nội tuyến

Sau đây là danh sách những gì nên được ghi lại trong các tệp WordPress

Hàm và phương thức lớp
Các lớp học
Các thành viên của lớp (bao gồm các thuộc tính và hằng số)
Yêu cầu và bao gồm
Móc (hành động và bộ lọc)
Nhận xét nội tuyến
tiêu đề tệp
hằng số

Tóm tắt phải rõ ràng, đơn giản và ngắn gọn. Tránh mô tả “tại sao” một yếu tố tồn tại, thay vào đó, hãy tập trung vào việc ghi lại “cái gì” và “khi nào” nó làm điều gì đó

Một hàm, hook, lớp hoặc phương thức là một yếu tố số ít của ngôi thứ ba, nghĩa là các động từ số ít của ngôi thứ ba nên được sử dụng để mô tả những gì mỗi người làm.

Mẹo
Cần trợ giúp ghi nhớ cách chia động từ số ít ngôi thứ ba?

Tốt. “(Nó) Làm gì đó. ”
Xấu. “(Nó) Làm gì đó. ”

ví dụ tóm tắt

Chức năng. Chức năng làm gì?
- Tốt. Hiển thị ngày sửa đổi cuối cùng cho một bài đăng
- Xấu. Hiển thị ngày mà bài đăng được sửa đổi lần cuối
bộ lọc. Những gì đang được lọc?
- Tốt. Lọc nội dung bài viết
- Xấu. Cho phép bạn chỉnh sửa nội dung bài đăng được xuất ra trong mẫu bài đăng
hành động. Khi nào một hành động cháy?
- Tốt. _Cháy sau khi phần lớn lõi được tải và người dùng được xác thực
- Xấu. _Cho phép bạn đăng ký các loại bài đăng tùy chỉnh, phân loại tùy chỉnh và các tác vụ quản lý chung khác sau khi tải nhiều lõi WordPress

Các yếu tố miêu tả nên được viết thành câu hoàn chỉnh. Một ngoại lệ đối với tiêu chuẩn này là tóm tắt tiêu đề tệp, được dự định dưới dạng "tiêu đề" tệp hơn là câu

Nên sử dụng dấu phẩy nối tiếp (Oxford) khi liệt kê các thành phần trong phần tóm tắt, mô tả và tham số hoặc trả về mô tả

tags and not syntax-highlighted.

 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...

2. Công cụ được đề xuất để sử dụng khi tìm kiếm phiên bản mà thứ gì đó đã được thêm vào WordPress là. Một tài nguyên bổ sung cho các móc cũ hơn là Cơ sở dữ liệu móc WordPress

Nếu không thể xác định số phiên bản sau khi sử dụng các công cụ này, hãy sử dụng ____0_______4

Mọi thứ được chuyển từ WPMU nên sử dụng

 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5. Không nên thay đổi thẻ  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5 hiện tại
Lập trình lại. Có thể loại bỏ các dòng bộ lọc hoặc hành động cụ thể đang được ghi lại để đáp ứng các tiêu chuẩn mã hóa, nhưng không cấu trúc lại mã khác trong tệp
Ghi chú
Các tiêu chuẩn tài liệu nội tuyến của WordPress dành cho PHP được thiết kế riêng để có đầu ra tối ưu trên Tham chiếu mã chính thức. Do đó, việc tuân theo các tiêu chuẩn cốt lõi và định dạng như được mô tả bên dưới là vô cùng quan trọng để đảm bảo đầu ra như mong đợi
DocBlocks phải trực tiếp đứng trước dòng hook, hành động, hàm, phương thức hoặc lớp. Không nên có bất kỳ thẻ mở/đóng hoặc những thứ khác giữa DocBlock và các khai báo để ngăn trình phân tích cú pháp bị nhầm lẫn
Không nên sử dụng đánh dấu HTML hoặc Markdown dưới bất kỳ hình thức nào trong phần tóm tắt. Nếu văn bản đề cập đến một phần tử hoặc thẻ HTML, thì nó phải được viết dưới dạng phần tử "thẻ hình ảnh" hoặc "img", không phải "_______0_______7". Ví dụ
Tốt. Kích hoạt khi in thẻ liên kết trong tiêu đề
Xấu. Kích hoạt khi in thẻ  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
8 trong tiêu đề
Các thẻ PHPDoc nội tuyến có thể được sử dụng
Đánh dấu HTML không bao giờ được sử dụng bên ngoài các ví dụ về mã, mặc dù có thể sử dụng Markdown khi cần trong phần mô tả
danh sáchSử dụng dấu gạch nối (-) để tạo danh sách không có thứ tự, với một dòng trống trước và sau
 * Description which includes an unordered list:
 *
 * - This is item 1.
 * - This is item 2.
 * - This is item 3.
 *
 * The description continues on ...
Sử dụng các số để tạo danh sách có thứ tự, với một dòng trống trước và sau
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
Các mẫu mã sẽ được tạo bằng cách thụt lề mỗi dòng mã bằng 4 khoảng trắng, với một dòng trống trước và sau. Các dòng trống trong các mẫu mã cũng cần được thụt vào bốn khoảng trắng. Lưu ý rằng các ví dụ được thêm vào theo cách này sẽ được xuất ra trong tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
Các liên kết ở dạng URL, chẳng hạn như vé Trac có liên quan hoặc tài liệu khác, nên được thêm vào vị trí thích hợp trong DocBlock bằng cách sử dụng thẻ  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
9.  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
Mọi chức năng, hook, lớp và phương thức phải có một phiên bản 
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2 tương ứng được liên kết với nó (thêm về điều đó bên dưới)
Không nên sử dụng HTML trong phần mô tả cho các thẻ 
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2, mặc dù có thể sử dụng Markdown hạn chế khi cần thiết, chẳng hạn như để thêm các dấu gạch ngược xung quanh các biến, đối số hoặc tên tham số, v.v. g.  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
2
Các phiên bản phải được thể hiện theo kiểu 3 chữ số 
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
3
 * @since 4.4.0
Nếu các thay đổi quan trọng đã được thực hiện đối với một chức năng, hook, lớp hoặc phương thức, thì nên thêm các thẻ, phiên bản và mô tả bổ sung 
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2 để cung cấp nhật ký thay đổi cho chức năng đó
“Những thay đổi đáng kể” bao gồm nhưng không giới hạn ở
Thêm đối số hoặc tham số mới
Đối số bắt buộc trở thành tùy chọn
Thay đổi hành vi mặc định/dự kiến
Các hàm hoặc phương thức trở thành trình bao bọc cho các API mới
Các tham số đã được đổi tên (khi PHP 8. 0 hỗ trợ đã được công bố)
PHPDoc hỗ trợ nhiều phiên bản 
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2 trong DocBlocks vì lý do rõ ràng này. Khi thêm các mục nhật ký thay đổi vào khối  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2, một phiên bản phải được trích dẫn và mô tả phải được thêm vào trường hợp và biểu mẫu câu và kết thúc bằng dấu chấm
 * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7,  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
8,  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
9. Không nên sử dụng HTML trong phần mô tả cho các thẻ này, mặc dù có thể sử dụng Markdown giới hạn khi cần thiết, chẳng hạn như để thêm các dấu gạch ngược xung quanh các biến, v.v. g.  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
2
Các thẻ nội tuyến  * @since 4.4.0
1 cũng có thể được sử dụng để tự động liên kết các hook trong lõi
Các giá trị mặc định hoặc có sẵn nên sử dụng dấu nháy đơn, e. g. 'bản nháp'. Các chuỗi có thể dịch phải được xác định như vậy trong phần mô tả
Các phần tử và thẻ HTML phải được viết dưới dạng “phần tử âm thanh” hoặc “thẻ liên kết”
Văn bản DocBlock sẽ xuống dòng tiếp theo sau 80 ký tự của văn bản. Nếu bản thân DocBlock được thụt lề ở vị trí 20 ký tự bên trái, thì dòng có thể xảy ra ở vị trí 100, nhưng không được vượt quá tổng chiều rộng 120 ký tự
Các ví dụ được cung cấp trong mỗi phần bên dưới hiển thị nội dung và thẻ DocBlock dự kiến, cũng như định dạng chính xác. Sử dụng khoảng trắng bên trong DocBlock, không phải tab và đảm bảo rằng các mục trong mỗi nhóm thẻ được căn chỉnh theo ví dụ
Các hàm và phương thức lớp phải được định dạng như sau
Bản tóm tắt. Giải thích ngắn gọn, một câu về mục đích của chức năng kéo dài tối đa hai dòng. Sử dụng một khoảng thời gian ở cuối
Sự miêu tả. Phần bổ sung cho phần tóm tắt, cung cấp mô tả chi tiết hơn. Dùng dấu chấm ở cuối câu
 * @since 4.4.0
2. Được sử dụng khi một phần tử chỉ dành cho mục đích sử dụng nội bộ và nên được bỏ qua khi phân tích cú pháp
 * @since 4.4.0
3. Phải luôn có 3 chữ số (e. g.  * @since 4.4.0
4). Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5
 * @since 4.4.0
6. Chỉ được sử dụng cho các chức năng hoặc lớp chỉ dành cho lõi triển khai các API lõi “riêng tư”. Nếu phần tử là riêng tư, nó sẽ được xuất ra với một thông báo cho biết ý định sử dụng nội bộ của nó
 * @since 4.4.0
1. Tham chiếu đến một hàm, phương thức hoặc lớp phụ thuộc nhiều vào bên trong. Xem ghi chú ở trên về các thẻ  * @since 4.4.0
1 nội tuyến để biết định dạng dự kiến
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
9. URL cung cấp thêm thông tin. Điều này không bao giờ được sử dụng để tham chiếu đến một hàm, móc, lớp hoặc phương thức khác, xem  * @since 4.4.0
1
 * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
1. Liệt kê các toàn cầu PHP được sử dụng trong hàm hoặc phương thức, với một mô tả tùy chọn về toàn cầu. Nếu nhiều hình cầu được liệt kê, chúng phải được căn chỉnh theo loại, biến và mô tả, với nhau dưới dạng một nhóm
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7. Lưu ý nếu tham số là Tùy chọn trước mô tả và bao gồm một khoảng thời gian ở cuối. Mô tả phải đề cập đến các giá trị được chấp nhận cũng như giá trị mặc định. Ví dụ. Không bắt buộc. Giá trị này làm một cái gì đó. Chấp nhận 'bài đăng', 'thời hạn' hoặc trống. Mặc định trống
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
9. Nên chứa tất cả các loại trả về có thể và mô tả cho từng loại. Sử dụng một khoảng thời gian ở cuối. Ghi chú. Không nên sử dụng  * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
4 bên ngoài các chủ đề đi kèm mặc định
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */
Các tham số là một mảng các đối số chỉ nên được ghi lại trong hàm “gốc” và được tham chiếu chéo qua thẻ 
 * @since 4.4.0
1 trong DocBlocks tương ứng
Các giá trị mảng phải được ghi lại bằng cách sử dụng kiểu ký hiệu băm của WordPress tương tự như cách có thể được ghi lại, mỗi giá trị mảng bắt đầu bằng thẻ 
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
8 và có dạng
*     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)
Một ví dụ về hàm "khởi tạo" và sử dụng lại một mảng đối số là
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 * @param type  $var Description.
 * @return type Description.
 */
Trong hầu hết các trường hợp, không cần đánh dấu các đối số riêng lẻ trong ký hiệu băm là tùy chọn, vì toàn bộ mảng thường là tùy chọn. Chỉ định “Tùy chọn. ” trong mô tả ký hiệu băm là đủ. Trong trường hợp mảng KHÔNG phải là tùy chọn, các cặp khóa/giá trị riêng lẻ có thể là tùy chọn và phải được đánh dấu là cần thiết
Nếu chức năng không còn được dùng nữa và không nên được sử dụng nữa, thẻ 
 * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
8, cùng với phiên bản và mô tả về những gì sẽ sử dụng thay thế, nên được thêm vào. Lưu ý việc sử dụng bổ sung thẻ  * @since 4.4.0
1 – Tham chiếu mã sử dụng thông tin này để cố gắng liên kết với chức năng thay thế
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 * @deprecated x.x.x Use new_function_name()
 * @see new_function_name()
 *
 * @param type $var Optional. Description.
 * @param type $var Description.
 * @return type Description.
 */
Lớp DocBlocks phải được định dạng như sau
Tóm lược. Một lời giải thích ngắn gọn, một câu về mục đích của lớp kéo dài tối đa hai dòng. Sử dụng một khoảng thời gian ở cuối
Sự miêu tả. Phần bổ sung cho phần tóm tắt, cung cấp mô tả chi tiết hơn. Sử dụng một khoảng thời gian ở cuối
 * @since 4.4.0
3. Phải luôn có 3 chữ số (e. g.  * @since 4.4.0
4). Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
0Nếu ghi lại một lớp con, sẽ rất hữu ích nếu bao gồm một tham chiếu thẻ 
 * @since 4.4.0
1 cho lớp cao nhất
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
12. 1. 1 thuộc tính
Thuộc tính lớp nên được định dạng như sau
Bản tóm tắt. Sử dụng một khoảng thời gian ở cuối
 * @since 4.4.0
3. Phải luôn có 3 chữ số (e. g.  * @since 4.4.0
4). Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */
7. Được định dạng giống như  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7, mặc dù phần mô tả có thể bị bỏ qua
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
22. 1. 2 hằng số
Bản tóm tắt. Sử dụng một khoảng thời gian ở cuối
 * @since 4.4.0
3. Phải luôn có 3 chữ số (e. g.  * @since 4.4.0
4). Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */
7. Được định dạng giống như  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7, mặc dù phần mô tả có thể bị bỏ qua
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
3Các tệp được yêu cầu hoặc bao gồm phải được ghi lại với mô tả tóm tắt DocBlock. Theo tùy chọn, điều này có thể áp dụng cho các cuộc gọi 
*     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)
4 nội tuyến nếu cần để làm rõ
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
4Cả hành động và hook bộ lọc phải được ghi lại trên đường dây ngay trước cuộc gọi tới 
*     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)
5 hoặc *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)
6 hoặc *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)
7 hoặc *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
*                     (aligned with Description, if wraps to a new line)
8 và được định dạng như sau
Tóm lược. Một lời giải thích ngắn gọn, một dòng về mục đích của hook. Sử dụng một khoảng thời gian ở cuối
Sự miêu tả. Một mô tả bổ sung cho bản tóm tắt, nếu được bảo đảm
 * @since 4.4.0
2. Được sử dụng khi hook chỉ dành cho mục đích sử dụng nội bộ và nên được bỏ qua khi phân tích cú pháp
 * @since 4.4.0
3. Phải luôn có 3 chữ số (e. g.  * @since 4.4.0
4). Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7. Nếu tham số là một mảng các đối số, hãy ghi lại từng đối số bằng ký hiệu băm (được mô tả ở trên trong phần Tham số là mảng) và bao gồm một dấu chấm ở cuối mỗi dòng
Lưu ý rằng 
 * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
9 không được sử dụng cho tài liệu hook, vì hook hành động không trả về kết quả nào và hook bộ lọc luôn trả về tham số đầu tiên của chúng
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
5Nếu một hook ở giữa một khối HTML hoặc một điều kiện dài, thì DocBlock phải được đặt trên dòng ngay trước khi bắt đầu khối HTML hoặc một điều kiện, ngay cả khi điều đó có nghĩa là buộc các thẻ ngắt dòng/PHP liên tục. 
Các công cụ để sử dụng khi tìm kiếm phiên bản mà hook đã được thêm vào là , hoặc Cơ sở dữ liệu về hook của WordPress dành cho các hook cũ hơn. Nếu sau khi sử dụng các công cụ này mà không thể xác định được số phiên bản, hãy sử dụng ____0_______4
Đôi khi, các hook sẽ được sử dụng nhiều lần trong cùng một tệp lõi hoặc các tệp lõi riêng biệt. Trong những trường hợp này, thay vì liệt kê toàn bộ DocBlock mỗi lần, chỉ phiên bản được thêm đầu tiên hoặc được đặt hợp lý nhất của một hành động hoặc bộ lọc mới được ghi lại đầy đủ. Các phiên bản tiếp theo sẽ có nhận xét một dòng
Đối với hành động
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
6Đối với bộ lọc
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
7Để xác định phiên bản nào sẽ được ghi lại, hãy tìm kiếm nhiều thẻ hook giống nhau, sau đó sử dụng để tìm lần sử dụng hook đầu tiên theo bản sửa đổi sớm nhất. Nếu nhiều phiên bản hook được thêm vào trong cùng một bản phát hành, hãy ghi lại phiên bản được đặt hợp lý nhất là "chính"
Nhận xét nội tuyến bên trong các phương thức và chức năng phải được định dạng như sau
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
8 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
9Lưu ý quan trọng. Nhận xét nhiều dòng không được bắt đầu bằng 
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 * @param type  $var Description.
 * @return type Description.
 */
8 (dấu hoa thị kép) vì trình phân tích cú pháp có thể nhầm nó với DocBlock. Thay vào đó, hãy sử dụng /**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @param type  $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 * @param type  $var Description.
 * @return type Description.
 */
9 (dấu hoa thị đơn)
Tiêu đề tệp DocBlock được sử dụng để cung cấp tổng quan về nội dung chứa trong tệp
Bất cứ khi nào có thể, tất cả các tệp WordPress phải chứa DocBlock tiêu đề, bất kể nội dung của tệp – điều này bao gồm các tệp chứa các lớp
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
0Phần Tóm tắt nhằm phục vụ như một mô tả ngắn gọn về mục đích cụ thể mà tệp phục vụ
ví dụ
Tốt. “API tiện ích. Lớp WP_Widget”
Xấu. “Lớp widget cốt lõi”
Phần Mô tả có thể được sử dụng để giải thích rõ hơn thông tin tổng quan về tệp, chẳng hạn như cách tệp cụ thể phù hợp với cấu trúc tổng thể của API hoặc thành phần
ví dụ
Tốt. “API Widgets bao gồm các lớp WP_Widget và WP_Widget_Factory cùng với nhiều chức năng cấp cao nhất triển khai các Widget và API thanh bên có liên quan. WordPress đăng ký một số widget phổ biến theo mặc định. ”
Hằng số DocBlock được sử dụng để đưa ra mô tả về hằng số nhằm giúp bạn hiểu và sử dụng tốt hơn
Hằng nên được định dạng như sau
Bản tóm tắt. Sử dụng một khoảng thời gian ở cuối
 * @since 4.4.0
3. Phải luôn có 3 chữ số (e. g.  * @since 4.4.0
4). Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5
/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */
7. Định dạng giống như  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7. Mô tả là tùy chọn
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
1Các thẻ PHPDoc phổ biến được sử dụng trong WordPress bao gồm 
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2,  * @since 4.4.0
1,  * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
1  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7 và  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
9 (xem bảng bên dưới để biết danh sách đầy đủ)
Phần lớn, các thẻ được sử dụng đúng cách, nhưng không phải lúc nào cũng vậy. Chẳng hạn, đôi khi bạn sẽ thấy một thẻ 
 tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
9 nội tuyến, liên kết với một chức năng hoặc phương thức riêng biệt. “Liên kết” với các lớp, phương thức hoặc chức năng đã biết là không cần thiết vì Tham chiếu mã sẽ tự động liên kết các phần tử này. Đối với các hook “liên kết” nội tuyến, thẻ thích hợp để sử dụng là  * @since 4.4.0
1 – xem phần Mô tả khác
TagUsageDescription_______15_______6riêng tưChỉ được sử dụng trong một số trường hợp hạn chế, chẳng hạn như khi không thể sử dụng công cụ sửa đổi khả năng hiển thị trong mã và chỉ khi ở chế độ riêng tư, chẳng hạn như đối với các chức năng chỉ dành cho lõi hoặc các lớp lõi triển khai API "riêng tư". Được sử dụng ngay bên dưới dòng  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2 trong khối.  * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
8phiên bản x. x. x Thay vào đó, hãy sử dụng tên chức năng thay thếPhiên bản nào của WordPress mà chức năng/phương thức không được dùng nữa. Sử dụng số phiên bản gồm 3 chữ số. Nên đi kèm với thẻ  * @since 4.4.0
1 phù hợp.  * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
1kiểu dữ liệu $variable description (Các) toàn cục tài liệu được sử dụng trong hàm/phương thức. Đối với các kiểu boolean và số nguyên, hãy sử dụng lần lượt là  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
07 và  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
08.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
09chuỗi thông tin Thường được sử dụng bọc trong  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
10 để thêm ghi chú chỉ sử dụng nội bộ.  * @since 4.4.0
2(độc lập) Được sử dụng để bỏ qua phân tích cú pháp toàn bộ phần tử.  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
9URLLiên kết đến thông tin bổ sung cho chức năng/phương pháp. Đối với tập lệnh/thư viện bên ngoài, hãy liên kết tới nguồn. Không được sử dụng cho các hàm/phương thức liên quan; .  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
14returntype descriptionHiển thị một phương thức "ma thuật" được tìm thấy bên trong lớp.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
15packagenameChỉ định gói mà tất cả các chức năng, bao gồm và định nghĩa trong tệp thuộc về. Tìm thấy trong DocBlock ở đầu tệp. Đối với các chủ đề cốt lõi (và đi kèm), đây luôn là WordPress.  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
7datatype $variable description Hàm/tham số phương thức của định dạng. loại tham số, tên biến, mô tả, hành vi mặc định. Đối với các kiểu boolean và số nguyên, hãy sử dụng lần lượt là  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
07 và  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
08.  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
9mô tả kiểu dữ liệuTài liệu về giá trị trả về của các hàm hoặc phương thức. Không nên sử dụng  * @since 3.0.0
 * @since 3.8.0 Added the `post__in` argument.
 * @since 4.1.0 The `$force` parameter is now optional.
4 bên ngoài các chủ đề đi kèm mặc định. Đối với các kiểu boolean và số nguyên, hãy sử dụng lần lượt là  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
07 và  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
08.  * @since 4.4.0
1elementname Tham chiếu đến hàm/phương thức/lớp khác mà hàm/phương thức dựa vào. Chỉ nên được sử dụng nội tuyến cho các hook "liên kết".  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
2phiên bản x. x. chức năng/phương pháp phiên bản phát hành xDocuments đã được thêm vào. Sử dụng số phiên bản gồm 3 chữ số – số này để hỗ trợ tìm kiếm phiên bản và để sử dụng khi so sánh các phiên bản trong mã. Ngoại lệ là  tags and not syntax-highlighted.
 * Description including a code sample:
 *
 *    $status = array(
 *        'draft'   => __( 'Draft' ),
 *        'pending' => __( 'Pending Review' ),
 *        'private' => __( 'Private' ),
 *        'publish' => __( 'Published' )
 *    );
 *
 * The description continues on ...
5.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
26(độc lập)Ghi chú. Thẻ này đã được sử dụng trong quá khứ, nhưng không nên được sử dụng nữa. Chỉ cần sử dụng từ khóa tĩnh trong mã của bạn là đủ để phpDocumentor trên PHP5+ nhận ra các biến và phương thức tĩnh và PhpDocumentor sẽ đánh dấu chúng là tĩnh.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
27datatype $variable descriptionLưu ý. Thẻ này đã được sử dụng trong quá khứ, nhưng không nên được sử dụng nữa. Ghi lại việc sử dụng một biến tĩnh trong một hàm/phương thức. Đối với các kiểu boolean và số nguyên, hãy sử dụng lần lượt là  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
07 và  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
08.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
30subpackagenameĐối với DocBlock cấp trang, chỉ định Thành phần mà tất cả các chức năng và định nghĩa trong tệp thuộc về. Đối với DocBlock cấp lớp, hãy chỉ định gói con/thành phần mà lớp đó thuộc về.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
31chuỗi thông tin Tài liệu đã lên kế hoạch thay đổi thành phần tử chưa được triển khai.  * Description text.
 *
 * @link https://core.trac.wordpress.org/ticket/20000
8mô tả kiểu dữ liệu cho một giá trị mảng đối số Được sử dụng để biểu thị các loại giá trị mảng đối số. Xem các phần Móc hoặc Tham số là Mảng để biết cú pháp ví dụ. lớp  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
33. tên phương thức()/lớp. $variablename / functionname()Lưu ý. Thẻ này đã được sử dụng trong quá khứ, nhưng không nên được sử dụng nữa. Tham chiếu một hàm/phương thức chính được sử dụng. Có thể bao gồm một mô tả ngắn. /**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description. Default.
 * @return type Description.
 */
7mô tả kiểu dữ liệuKiểu dữ liệu cho biến lớp và mô tả ngắn. Cuộc gọi lại được đánh dấu gọi lại
Ghi chú
Các thẻ PHPDoc hoạt động với một số trình soạn thảo văn bản/IDE để hiển thị thêm thông tin về một đoạn mã. Nó hữu ích cho các nhà phát triển sử dụng các trình chỉnh sửa đó để hiểu mục đích là gì và họ sẽ sử dụng nó ở đâu trong mã của họ. PhpStorm và Netbeans đã hỗ trợ PHPDoc
Các trình soạn thảo văn bản/IDE sau đây có các gói/tiện ích mở rộng mà bạn có thể cài đặt để giúp bạn tự động tạo DocBlocks
Ghi chú. Ngay cả khi có trợ giúp tạo DocBlocks, hầu hết các trình chỉnh sửa mã không thực hiện công việc kỹ lưỡng – có khả năng bạn sẽ cần điền thủ công vào một số khu vực nhất định của bất kỳ DocBlocks nào được tạo
lời nói đầu. Hiện tại và để đảm bảo tính nhất quán, WordPress Core sẽ tiếp tục sử dụng ____7_______30 thẻ – cả khi viết DocBlocks mới và chỉnh sửa những cái cũ
Chỉ khi các đề xuất PSR-5 mới – bên ngoài – được hoàn thiện, các thay đổi trên toàn bộ mới được xem xét, chẳng hạn như ngừng sử dụng một số thẻ nhất định
Như đã đề xuất trong các đề xuất PSR-5 mới, thẻ PHPDoc sau sẽ không được dùng nữa
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
30 (có lợi cho thẻ gói thống nhất.  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
37)
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
26 (không còn cần thiết nữa)
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
27 (không còn cần thiết)
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
15 Thẻ trong Plugin và Chủ đề (không bao gồm các chủ đề đi kèm)
Các tác giả chủ đề và plugin của bên thứ ba không được sử dụng 
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
41 trong các plugin hoặc chủ đề của họ. Tên  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
15 cho phần bổ trợ phải là tên phần bổ trợ; .  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
43
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
44 Thẻ
Chính sách của WordPress là không sử dụng thẻ 
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
44, ngoại trừ trường hợp duy trì nó trong các thư viện bên ngoài. Chúng tôi không muốn ngụ ý bất kỳ loại “sở hữu” nào đối với mã có thể ngăn cản sự đóng góp
Thẻ 
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
46 và  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
47
Các thẻ 
 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
46 và  * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The description continues on ...
47 được sử dụng trong các thư viện và tập lệnh bên ngoài và không được sử dụng trong các tệp cốt lõi của WordPress
 
			@param nghĩa là gì trong PHP?
			Thẻ @param  được sử dụng để ghi lại một đối số của hàm hoặc phương thức . 
		
			Làm thế nào để viết PHPDoc?
			Tạo khối PHPDoc cho cấu trúc mã . 
 Đặt dấu mũ trước cấu trúc mã được yêu cầu (lớp, phương thức, chức năng, v.v.), nhập nhận xét khối mở /** và nhấn Enter
 Trong menu ngữ cảnh của trình soạn thảo, chọn Tạo. Tạo khối PHPDoc và chọn cấu trúc mã để tạo nhận xét PHPDoc cho