Docblock trong phpdocumentor là gì?

Nếu bạn đã từng thử đọc mã do người khác viết (ai chưa từng đọc?), thì bạn biết đó có thể là một nhiệm vụ khó khăn. Một mớ “mã spaghetti” trộn lẫn với vô số biến được đặt tên kỳ lạ khiến bạn quay cuồng. Chức năng này mong đợi một chuỗi hoặc một mảng?

PhpDoc, viết tắt của PhpDocumentor, là một công cụ mạnh mẽ cho phép bạn dễ dàng ghi lại mã của mình thông qua các nhận xét được định dạng đặc biệt. Tài liệu sẽ có sẵn không chỉ trong mã nguồn mà còn trong tài liệu chuyên nghiệp được trích xuất bằng web hoặc giao diện dòng lệnh. Kết quả có thể ở nhiều định dạng khác nhau như HTML, PDF và CHM. Ngoài ra, nhiều IDE cung cấp khả năng hoàn thành mã có thể phân tích các nhận xét PhpDoc và cung cấp các tính năng hữu ích như gợi ý kiểu. Bằng cách sử dụng PhpDoc, bạn có thể giúp người khác (và chính bạn) dễ dàng hiểu mã của bạn – hàng tuần, hàng tháng và thậm chí hàng năm sau khi bạn viết nó

Cách dễ nhất để cài đặt PhpDoc là với PEAR. Tất nhiên, trước khi bạn có thể làm như vậy, bạn phải cài đặt PEAR. Nếu không, hãy làm theo hướng dẫn tại lê. php. net/thủ công/vi/cài đặt. php

Trong bài viết này, tôi sẽ chỉ cho bạn cách sử dụng PhpDoc để tạo tài liệu tuyệt đẹp và thân thiện với người dùng từ đầu đến cuối

khối tài liệu

DocBlock là một nhận xét kiểu C nhiều dòng được sử dụng để ghi lại một khối mã. Nó bắt đầu bằng

>Hello, world!<>
 */

0 và có dấu hoa thị ở đầu mỗi dòng. Đây là một ví dụ

DocBlocks bao gồm ba phần. mô tả ngắn, mô tả dài và thẻ. Tất cả ba phần là tùy chọn

Mô tả ngắn là một mô tả ngắn gọn được kết thúc bằng một dòng mới hoặc một dấu chấm. Quy trình phân tích cú pháp của PhpDoc rất thông minh;

Phần mô tả dài là nơi chứa phần lớn tài liệu;

Cả mô tả dài và ngắn có thể chứa một số phần tử HTML nhất định để định dạng. Các thẻ HTML không được hỗ trợ sẽ được hiển thị dưới dạng văn bản thuần túy. Tuy nhiên, PhpDoc có thể tạo tài liệu ở nhiều định dạng, do đó, các thẻ HTML không nhất thiết phải được hiển thị giống như trong tệp HTML; . Nếu bạn cần hiển thị thẻ HTML dưới dạng văn bản, hãy sử dụng dấu ngoặc kép. Ví dụ

>Hello, world!<>
 */

Phần thẻ của DocBlock chứa bất kỳ số lượng thẻ đặc biệt nào được biểu thị bằng ký hiệu

>Hello, world!<>
 */

1. Các thẻ được sử dụng để chỉ định thông tin bổ sung, chẳng hạn như các tham số dự kiến ​​và loại của chúng. Hầu hết các thẻ phải nằm trên dòng riêng của chúng, ngoại trừ một số thẻ nhất định có thể nằm trong dòng. Các thẻ nội tuyến được bao quanh bởi dấu ngoặc nhọn và có thể nằm trong cả mô tả dài và ngắn. Để biết danh sách đầy đủ các thẻ, hãy xem tài liệu PhpDoc có liên quan

Nếu bạn cần bắt đầu một dòng bằng ký hiệu

>Hello, world!<>
 */

1 nhưng bạn không muốn nó được hiểu là một thẻ, bạn có thể thoát nó bằng dấu gạch chéo ngược

PhpDoc sẽ tự động nhận dạng danh sách văn bản trong các mô tả dài và ngắn và nó sẽ phân tích cú pháp chúng. Tuy nhiên, nó sẽ không phân tích danh sách lồng nhau một cách chính xác. Nếu bạn muốn sử dụng danh sách lồng nhau, hãy sử dụng các thẻ HTML. Đây là một ví dụ để minh họa những gì tôi muốn nói

 *   
Item 1
 *   

 *     
Item 1.1
 *     
Item 1.2
 *   
 *   
Item 2
 * 
 */

gói

Các gói PhpDoc được sử dụng để nhóm các phần tử mã có liên quan trong tài liệu được tạo. Bạn có thể chỉ định các gói cho các tệp và lớp và mã tài liệu mà chúng chứa sẽ kế thừa gói từ chúng. Để chỉ định một gói, hãy đặt thẻ

>Hello, world!<>
 */

3 trong DocBlock cấp tệp hoặc cấp lớp (DocBlock cấp tệp và cấp lớp sẽ được thảo luận thêm ở phần sau). Tên gói có thể chứa các chữ cái, số, dấu gạch ngang, dấu gạch dưới và dấu ngoặc vuông (“[” và “]”)

Dưới đây là một ví dụ về việc xác định gói của tệp

Nếu bạn có nhiều cấp gói và gói phụ, bạn có thể xác định gói phụ bằng thẻ

>Hello, world!<>
 */

4. Đây là một ví dụ

Nếu một tệp hoặc lớp không chỉ định gói, nó sẽ được đặt thành gói mặc định, “mặc định”. Bạn có thể chỉ định một gói khác sẽ được sử dụng theo mặc định khi tạo tài liệu thông qua tùy chọn dòng lệnh

>Hello, world!<>
 */

5

Tôi có thể làm tài liệu gì?

Không phải tất cả các phần tử mã đều có thể được ghi lại bằng DocBlocks. Đây là danh sách các yếu tố mã có thể được ghi lại

• Các tập tin
• Các lớp học
• Hàm và phương thức
• Thuộc tính lớp
• biến toàn cầu

• >Hello, world!<>
   */

  6/

  >Hello, world!<>
   */

  7

• >Hello, world!<>
   */

  8

Tất cả các phần tử này có thể sử dụng một số thẻ chung nhất định, nhưng mỗi phần tử có các thẻ dành riêng cho phần tử đó. Tôi sẽ xem qua một số yếu tố và thẻ thường được sử dụng để ghi lại chúng

Các tập tin

DocBlocks cấp tệp được sử dụng để ghi lại nội dung của tệp. Chúng tôi khuyên bạn nên bao gồm DocBlock ở cấp độ tệp trong mọi tệp tài liệu của bạn và trên thực tế, PhpDoc sẽ hiển thị cảnh báo nếu không tìm thấy DocBlock khi tạo tài liệu

Hầu hết các phần tử được ghi lại bằng cách đặt DocBlock trước phần tử, nhưng các tệp là một ngoại lệ (vì bạn không thể viết bất kỳ thứ gì trước một tệp). DocBlocks cấp tệp được đặt trên dòng đầu tiên của tệp

DocBlock cấp tệp thường chứa các thẻ

>Hello, world!<>
 */

3,

>Hello, world!<>
 */

4,

 *   
Item 1
 *   

 *     
Item 1.1
 *     
Item 1.2
 *   
 *   
Item 2
 * 
 */

1 và

 *   
Item 1
 *   

 *     
Item 1.1
 *     
Item 1.2
 *   
 *   
Item 2
 * 
 */

2. Các thẻ

>Hello, world!<>
 */

3 và

>Hello, world!<>
 */

4 đã được thảo luận trước đó. Thẻ

 *   
Item 1
 *   

 *     
Item 1.1
 *     
Item 1.2
 *   
 *   
Item 2
 * 
 */

1 được sử dụng để chỉ định URL tới giấy phép bên ngoài bao gồm mã của bạn. Thẻ phải chứa URL của giấy phép và tiêu đề tùy chọn. Thẻ

 *   
Item 1
 *   

 *     
Item 1.1
 *     
Item 1.2
 *   
 *   
Item 2
 * 
 */

2 được sử dụng để chỉ định tác giả của tệp. Nó phải chứa tên của tác giả và tùy chọn một địa chỉ email trong dấu ngoặc nhọn

Không giống như hầu hết các phần tử, DocBlock cấp tệp phải chứa thẻ

>Hello, world!<>
 */

3 để được phân tích cú pháp chính xác

Dưới đây là một ví dụ hoàn chỉnh về DocBlock cấp tệp

>Hello, world!<>
 */

3

Các lớp học

DocBlock cấp lớp được đặt trước định nghĩa lớp và phải mô tả ý nghĩa của lớp. Giống như DocBlocks cấp tệp, DocBlocks cấp lớp thường chứa các thẻ

>Hello, world!<>
 */

3,

>Hello, world!<>
 */

4 và

 *   
Item 1
 *   

 *     
Item 1.1
 *     
Item 1.2
 *   
 *   
Item 2
 * 
 */

2. Đây là một ví dụ

>Hello, world!<>
 */

7

Hàm và phương thức

Các hàm và phương thức được ghi lại giống hệt nhau trong PhpDoc. (Đối với những người có thể không quen thuộc với thuật ngữ này, một phương thức chỉ là một chức năng trong một lớp. ) Các hàm và phương thức thường chứa các thẻ

1 và

2 trong DocBlocks của chúng. Thẻ

1 được sử dụng để ghi lại loại thông số dự kiến. Nó chứa ba phần. tham số, kiểu dữ liệu và mô tả tùy chọn. Thẻ

2 được sử dụng để ghi lại kiểu trả về. Nó bao gồm hai phần. kiểu dữ liệu và mô tả tùy chọn. Trong cả hai thẻ, kiểu dữ liệu có thể là kiểu dữ liệu PHP hợp lệ, tên lớp hoặc “hỗn hợp”. Nó cũng có thể chứa nhiều tùy chọn được phân tách bằng một đường ống

>Hello, world!<>
 */

2

Tạo tài liệu

Khi bạn đã ghi lại mã PHP của mình, bạn sẽ muốn tạo tài liệu thân thiện với người dùng từ đó. Để làm như vậy, hãy chạy công cụ dòng lệnh PhpDoc

>Hello, world!<>
 */

3

Tùy chọn

5 chỉ định danh sách thư mục được phân tách bằng dấu phẩy chứa các tệp để tạo tài liệu và

6 đường dẫn đến tài liệu được tạo.

7 được sử dụng để chỉ định tiêu đề dự án và

>Hello, world!<>
 */

5 để đặt tên gói mặc định. Cuối cùng,

9 chỉ định định dạng tài liệu. PhpDoc có nhiều lựa chọn định dạng để lựa chọn. Danh sách đầy đủ có sẵn trên trang web PhpDoc

Bạn có thể tìm hiểu thêm về công cụ dòng lệnh bằng cách thực hiện lệnh trợ giúp như sau

>Hello, world!<>
 */

9

Sau khi bạn chạy lệnh, đường dẫn tài liệu mà bạn đã chỉ định sẽ chứa các tài liệu đã tạo

Đối với những người không thoải mái khi sử dụng giao diện dòng lệnh, PhpDoc cũng có sẵn giao diện web. Nó nằm ngoài phạm vi bài viết này để thảo luận chi tiết về nó, nhưng bạn có thể đọc thêm về nó trên trang web chính thức của PhpDoc, phpdoc. tổ chức

Bản tóm tắt

Trong bài viết này, tôi đã cung cấp cho bạn cái nhìn đầu tiên về PhpDoc và nhiều tính năng mạnh mẽ của nó. Tôi đã giải thích mục đích của DocBlocks và các thành phần của chúng; . Tôi thực sự khuyên bạn nên bắt đầu sử dụng PhpDoc trong các dự án của riêng mình, thậm chí chỉ để ghi lại những phần quan trọng nhất. Nó rất đơn giản và sẽ giúp bạn và đồng nghiệp của bạn tiết kiệm vô số thời gian cho việc cắn móng tay và giật tóc

Hình ảnh qua Zadorozhnyi Viktor / Shutterstock

Chia sẻ bài viết này

Moshe Teutsch

Moshe Teutsch là một nhà phát triển web và doanh nhân tự do. Anh ấy chuyên về lập trình PHP và hiện đang cho thuê. Trong thời gian rảnh rỗi, anh ấy thích chơi cờ, hát, viết, đọc, triết học và viết mã bằng các ngôn ngữ lập trình bí truyền

Khối tài liệu là gì?

Trong lập trình, docblock hoặc DocBlock là một nhận xét được định dạng đặc biệt được chỉ định trong mã nguồn được sử dụng để ghi lại một đoạn mã cụ thể . Điều này làm cho định dạng DocBlock độc lập với ngôn ngữ đích (miễn là nó hỗ trợ nhận xét); .

Tài liệu trong PHP là gì?

PHPDoc là bản chuyển thể của Javadoc dành cho ngôn ngữ lập trình PHP . Nó vẫn là một tiêu chuẩn không chính thức để bình luận mã PHP, nhưng nó đang trong quá trình được chính thức hóa.

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 phần tử này. bao gồm câu lệnh, đị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 .