Ví dụ về PHPDoc

Nếu bạn đã phát triển trong bất kỳ khoảng thời gian nào dài hơn khoảng 5 phút, rất có thể ai đó đã nói với bạn về tầm quan trọng của việc ghi lại mã của bạn một cách chính xác. Và giống như một người tốt không muốn làm em bé khóc, tôi biết bạn muốn đưa ra tất cả các nhận xét cần thiết trong mã của mình, để thế giới hiểu được kiệt tác của bạn

Nhưng mã bình luận là không đủ. Với PHPTools, họ có thể di chuột qua các lệnh gọi hàm và xem bản tóm tắt của lệnh gọi đó. như vậy

Nhưng - hơi khó chịu khi khiến mọi người phải thu thập thông tin trên toàn bộ mã của bạn để tìm các chức năng đang được sử dụng rồi quay lại viết mã. Điều gì sẽ xảy ra nếu có một công cụ có thể lấy tất cả các nhận xét được ghi lại trong mã, thu thập chúng vào các trang HTML với các liên kết giữa các phương thức và giải thích chi tiết về chức năng của từng lớp, phương thức và biến?

Tốt. Vâng, nó làm. Nó được gọi là PHPDocumentor, viết tắt là PHPDoc

PHPDocumentor - Tóm tắt

PHPDocumentor - được gọi tắt là PHPDoc - đã trở thành hệ thống tài liệu "thực tế" cho PHP. Đây thực sự là một chương trình dựa trên PHP - sử dụng khái niệm "ăn thức ăn cho chó của chính bạn"* trường phái phát triển phần mềm

* "Ăn thức ăn cho chó của bạn" không có nghĩa là xấu. Nó có nghĩa là sử dụng phần mềm của riêng bạn để đạt được mục tiêu của bạn. Các nhà phát triển nên ăn thức ăn cho chó của họ khi có thể, để họ có cùng trải nghiệm với người dùng của họ

Những gì PHPDocumentor làm là đọc qua một thư mục mã PHP, tìm kiếm các tệp PHP và trích xuất các nhận xét với định dạng đặc biệt. Đây là một ví dụ điển hình

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */

Các nhận xét được định dạng PHPDoc này được dịch sang HTML, tạo tài liệu giải thích chức năng của từng lớp, hàm hoặc biến mà không cần mọi người phải đọc qua toàn bộ mã. Họ có thể sử dụng các trang PHPDoc HTML để xem nhanh cách thức hoạt động của phần mềm, chức năng sử dụng cho các biến, chức năng trả về là gì hoặc các thông tin hữu ích khác mà nhà phát triển đã quyết định là quan trọng

PHPDoc không tạo nhận xét và tài liệu cho bạn - bạn vẫn phải nhập thông tin chi tiết. Nhưng nó có thể thu thập những nhận xét đó cho bạn và PHPTools giúp việc đó trở nên dễ dàng hơn

PHPDocumentor 2 - Cài đặt

PHPDocumentor có thể được cài đặt thông qua PEAR, PHAR hoặc nhà soạn nhạc. Nhưng - PHPDocumentor mặc định được thiết kế cho PHP5. Nếu bạn đang chạy PHP7, bạn sẽ gặp phải các vấn đề chẳng hạn như sự khác biệt trong cách hoạt động của mảng hoặc các vấn đề nhỏ khác nếu bạn sử dụng phương thức PEAR tiêu chuẩn. Vì vậy, quy tắc đầu tiên - nếu bạn định sử dụng PHP7, đừng cài đặt PHPDocumentor với PEAR

Thay vào đó, hãy xem PHPDocumentor2 có tại https. //github. com/phpDocumentor/phpDocumentor2 - điều này được tạo ra để tuân thủ PHP7. Có một số vấn đề về cách thiết lập nó, vì vậy đây là một cách hoạt động tốt cho các hệ thống dựa trên UNIX và Mac thông qua quy trình này

Sau khi nó được cài đặt, bạn chạy nó thông qua lệnh php PATHTOFILE/phpDocumentor.phar. Trong ví dụ trên, đó sẽ là php /usr/local/bin/phpDocumentor.phar

Đừng chạy nó ngay bây giờ nếu bạn không có tệp PHP để làm tài liệu - bạn sẽ có một trải nghiệm đáng thất vọng vì sẽ không có gì xảy ra. Nếu bạn muốn sử dụng PHPDoc, trước tiên bạn phải tạo một số tài liệu PHPDoc trong các tệp PHP của mình

Bổ sung tùy chọn

PHPDoc có thể tự làm hầu hết mọi thứ, nhưng nếu bạn muốn có một số hình ảnh đẹp đi kèm với nó, hãy có https. //www. graphviz. org/ đã cài đặt nó một điểm cộng. Nó không bắt buộc, nhưng nếu PHPDoc không thể tìm thấy nó, nó sẽ đưa ra cảnh báo cho bạn rằng nó sẽ thực sự, thực sự hữu ích. Lưu ý rằng nó phải có sẵn cho PHPDoc, vì vậy nó phải có trong câu lệnh đường dẫn của bạn. Đối với những người đang chạy Mac, nó có thể được cài đặt qua Homebrew với

brew install graphviz

Định dạng tài liệu PHPDoc

Nhận xét PHPDoc luôn tiến hành những gì họ đang mô tả. Đây có thể là một hàm, một lớp, hằng - danh sách đầy đủ ở đây

• Chức năng
• Không thay đổi
• Lớp học
• giao diện
• Đặc điểm
• Hằng số lớp
• Tài sản
• Phương pháp

Lấy ví dụ trước của chúng ta, Nó xuất hiện ngay trước một hàm, như vậy

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

Nhận xét được định dạng PHPDoc theo mẫu này

• Bản tóm tắt. Những gì bình luận đang mô tả. Nên rất ngắn, khoảng một dòng
• Sự miêu tả. Thịt của bình luận. Đây là nơi bạn có thể mô tả cách thức hoạt động của đoạn mã sau, tại sao nó lại ở đó, bất kỳ "sự cố" nào mà người dùng nên biết
• thẻ. Một hoặc nhiều thẻ định dạng PHPDoc xác định tác giả, tham số hàm hoặc trả về, phiên bản, v.v. Có một danh sách đầy đủ các thẻ

Hãy quay lại ví dụ của chúng tôi và giải thích thêm một chút. Nó đang mô tả một hàm có tên là ReturnMessage có hai tham số - $status và

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

Một trong những điều thú vị là nếu bạn đang sử dụng PHPTools và nhập một thẻ, bạn chỉ cần nhấn

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

Đây là một phiên bản cập nhật

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * 
 * This takes the status and a message, and returns a JSON string in the format: 
 * { status: $status,
 *   message: $message
 * }
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 * @author John Hummel 
 * @version ${1:1.0.0
 * @return String
 */

Hãy nhớ rằng các nhận xét PHPDoc phải ở ngay trước mục mà chúng đang mô tả. Ví dụ: nếu chúng tôi có Lớp PHP

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

/**
 * This object tracks the information for a customer, including first name, last name, and other relevant details.
 * 
 * @author John Hummel 
 * @version ${1:1.0.0
 */
class Customer
{
    private $firstName;
    private $firstName;

    /**
     * Sets the $firstName of this object.
     * 
     * If the $newFirstName is empty or null, $firstName will not be changed.  Otherwise, $firstName will be set to the same value as $newFirstName.
     * @param mixed $newFirstname The submitted first name to update this object to.
     * @return boolean true if the $newFirstName is accepted, otherwise false.
     */
    public function SetFirstName($newFirstName)
    {
        if(empty($newFirstName))
        {
            return false;
        }
        else
        {
            $firstName = $newFirstname;
            return true;
        }

    }
}

Bây giờ chúng tôi có nhận xét PHPDoc của mình, hãy tạo tài liệu của chúng tôi

Tạo tài liệu PHPDoc

Bây giờ các nhà phát triển của bạn đã thêm vào tất cả các nhận xét dựa trên PHPDoc (có thể được hỗ trợ bởi một người tài năng và thậm chí chúng ta có thể nói - nhà văn kỹ thuật ưa nhìn để hỗ trợ), hãy thực sự tạo PHPDoc của chúng ta

Từ dòng lệnh, chúng tôi điều hướng đến thư mục chứa tất cả các tệp PHP của chúng tôi và chạy

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

Tùy thuộc vào hệ điều hành bạn đang chạy, điều này thường là đủ. Tôi đã thấy tốt hơn là ít nhất nên chạy

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

Tham số

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 */
function ReturnMessage($status, $message) 

• /**
   * Displays an error message that can be processed by JSON accepting systems.
   * @param mixed $status Status of either success or failure.
   * @param mixed $message The message to be returned.
   */
  function ReturnMessage($status, $message) 

  7 - chỉ định thư mục đầu ra

• /**
   * Displays an error message that can be processed by JSON accepting systems.
   * @param mixed $status Status of either success or failure.
   * @param mixed $message The message to be returned.
   */
  function ReturnMessage($status, $message) 

  8 - chỉ định tệp nào sẽ chạy PHPDoc trên đó

• /**
   * Displays an error message that can be processed by JSON accepting systems.
   * @param mixed $status Status of either success or failure.
   * @param mixed $message The message to be returned.
   */
  function ReturnMessage($status, $message) 

  9 - Yêu cầu PHPDoc "Bỏ qua các tệp hoặc thư mục này" - điều này hữu ích nếu bạn có một thư viện hoặc khung trong thư mục đó và bạn muốn ghi lại các tệp của mình chứ không phải mọi thứ

Nếu chúng tôi chỉ chạy phiên bản chung, các tệp PHPDoc sẽ được đặt trong thư mục bản dựng. Đây là bảng phân tích các tệp mà PHPDoc tạo dựa trên ví dụ của chúng tôi

└── build
    ├── api-cache
    │   ├── 0fea6a13c52b4d47
    │   │   └── 25368f24b045ca84
    │   │       └── 38a865804f8fdcb6
    │   │           └── 57cd99682e939275
    │   │               └── ed16c38ee25ae267
    │   │                   └── e4a7fb4bf8c9c269.php
    │   └── 1952a01898073d1e
    │       └── 561b9b4f2e42cbd7
    │           └── 38a865804f8fdcb6
    │               └── 57cd99682e939275
    │                   └── ed16c38ee25ae267
    └── docs
        ├── classes
        │   └── Customer.html
        ├── css
        │   ├── bootstrap-combined.no-icons.min.css
        │   ├── font-awesome.min.css
        │   ├── jquery.iviewer.css
        │   ├── phpdocumentor-clean-icons
        │   │   ├── Read\ Me.txt
        │   │   ├── fonts
        │   │   │   ├── phpdocumentor-clean-icons.dev.svg
        │   │   │   ├── phpdocumentor-clean-icons.eot
        │   │   │   ├── phpdocumentor-clean-icons.svg
        │   │   │   ├── phpdocumentor-clean-icons.ttf
        │   │   │   └── phpdocumentor-clean-icons.woff
        │   │   ├── lte-ie7.js
        │   │   └── style.css
        │   ├── prism.css
        │   └── template.css
        ├── files
        │   ├── PHPDocSample.html
        │   └── PHPDocSample.php.txt
        ├── font
        │   ├── FontAwesome.otf
        │   ├── fontawesome-webfont.eot
        │   ├── fontawesome-webfont.svg
        │   ├── fontawesome-webfont.ttf
        │   └── fontawesome-webfont.woff
        ├── graphs
        │   ├── class.html
        │   └── classes.svg
        ├── images
        │   ├── apple-touch-icon-114x114.png
        │   ├── apple-touch-icon-72x72.png
        │   ├── apple-touch-icon.png
        │   ├── custom-icons.svg
        │   ├── favicon.ico
        │   ├── hierarchy-item.png
        │   ├── icon-class-13x13.png
        │   ├── icon-class.svg
        │   ├── icon-interface-13x13.png
        │   ├── icon-interface.svg
        │   ├── icon-trait-13x13.png
        │   ├── icon-trait.svg
        │   └── iviewer
        │       ├── grab.cur
        │       ├── hand.cur
        │       ├── iviewer.rotate_left.png
        │       ├── iviewer.rotate_right.png
        │       ├── iviewer.zoom_fit.png
        │       ├── iviewer.zoom_in.png
        │       ├── iviewer.zoom_out.png
        │       └── iviewer.zoom_zero.png
        ├── index.html
        ├── js
        │   ├── bootstrap.min.js
        │   ├── html5.js
        │   ├── jquery-1.11.0.min.js
        │   ├── jquery.dotdotdot-1.5.9.js
        │   ├── jquery.dotdotdot-1.5.9.min.js
        │   ├── jquery.iviewer.js
        │   ├── jquery.iviewer.min.js
        │   ├── jquery.mousewheel.js
        │   ├── jquery.smooth-scroll.js
        │   ├── prism.min.js
        │   └── ui
        │       └── 1.10.4
        │           └── jquery-ui.min.js
        ├── namespaces
        │   └── default.html
        └── reports
            ├── deprecated.html
            ├── errors.html
            └── markers.html

Phew - đó là rất nhiều thứ, và hầu hết trong số đó là mặc định. Điều quan trọng nhất cần lưu ý là tệp

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * 
 * This takes the status and a message, and returns a JSON string in the format: 
 * { status: $status,
 *   message: $message
 * }
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 * @author John Hummel 
 * @version ${1:1.0.0
 * @return String
 */

/**
 * Displays an error message that can be processed by JSON accepting systems.
 * 
 * This takes the status and a message, and returns a JSON string in the format: 
 * { status: $status,
 *   message: $message
 * }
 * @param mixed $status Status of either success or failure.
 * @param mixed $message The message to be returned.
 * @author John Hummel 
 * @version ${1:1.0.0
 * @return String
 */

Phần kết luận

Tôi không thể nhấn mạnh tầm quan trọng của tài liệu tốt đối với các dự án của bạn. Nó không chỉ giúp ích cho những người khác mà còn giúp ích cho chính bạn, vì vậy khi bạn bắt đầu lướt qua mã của mình để tìm lỗi, bạn có thể tìm thấy con đường logic của mình. PHPDoc có thể giúp bạn, khách hàng của bạn hoặc các nhà phát triển đồng nghiệp của bạn nhanh chóng thấy cách hoạt động của mã để họ có thể quay lại làm việc

PHPDoc là gì và tại sao bạn lại sử dụng nó?

Làm thế nào để viết PHPDoc?

Làm cách nào để sử dụng PhpDocumentor?

Thẻ PHPDoc là gì?