Nhận xét phương thức php

Một chú thích trong mã PHP là một dòng không được thực thi như một phần của chương trình. Mục đích duy nhất của nó là được đọc bởi một người đang xem mã

Nhận xét có thể được sử dụng để

• Hãy để người khác hiểu mã của bạn
• Nhắc nhở bản thân về những gì bạn đã làm - Hầu hết các lập trình viên đều có kinh nghiệm quay lại công việc của họ sau một hoặc hai năm và phải tìm hiểu lại những gì họ đã làm. Nhận xét có thể nhắc nhở bạn về những gì bạn đã nghĩ khi viết mã

PHP hỗ trợ một số cách bình luận

Thí dụ

Cú pháp cho chú thích một dòng

// Đây là comment một dòng

# Đây cũng là nhận xét một dòng
?>

Tự mình thử »

Thí dụ

Cú pháp comment nhiều dòng

/*
Đây là khối nhận xét nhiều dòng
kéo dài trên nhiều
dòng
*/
?>

Tự mình thử »

Thí dụ

Sử dụng nhận xét để loại bỏ các phần của mã

// Bạn cũng có thể sử dụng nhận xét để loại bỏ các phần của dòng mã
$x = 5 /* + 15 */ + 5;
echo $x;
?>

Tự mình thử »

Các nhà phát triển thường viết ra một lượng lớn mã bao gồm API và các thành phần khác trong dự án trung bình cho đến lớn. Mặc dù có một quy ước về mã viết, mỗi nhà phát triển đều có một bình luận cá nhân và các tiêu chuẩn viết tài liệu. Một số khác ghi chú khó hiểu nhỏ khi những người khác đính kèm tài liệu Google Docs đầy đủ ghi lại phương thức hoặc lớp một cách chi tiết. Vấn đề này trở nên rất quan trọng khi số lượng người dùng cuối ngày càng tăng lên và cần phải có tài liệu hướng dẫn thích hợp cho dự án. Trong trường hợp các API, đặc biệt là các API REST, một công cụ tạo ra tài liệu API REST trở nên cần thiết vì sự phân bố và sử dụng rộng rãi của API

Bây giờ tôi sẽ bắt đầu ví dụ với một đoạn mã

namespace SearchElastic;
 
use SearchElastic\SearchAbstract\SearchAbstract;
 
/**
 
*  Class to perform basic search extends from SearchElastic\SearchAbstract\SearchAbstract
 
*/
 
class Search extends SearchAbstract
 
{
 
   /**
 
    * Search in Elasticsearch.
 
    *
 
    * @param  string  $query
 
    * @return Result from elasticsearch
 
    */
 
   public function search($query)
 
   {
 
       $this->validate($query);
 
       $client = $this->client->getClient();
 
       $result = array();
 
       // Change the match column name with the column name you want to search in it.
 
       $params = [
 
               'index' => $this->client->getIndex(),
 
               'type'  => $this->client->getType(),
 
               'body'  => [
 
                   'query' => [
 
                       'match' => [ $this->searchColumn => $query],
 
                   ],
 
               ],
 
           ];
 
       $query  = $client->search($params);
 
       return  $this->extractResult($query);
 
   }
 
}

Please comment about the comment of the phase code on

/**

    * Search in Elasticsearch.

    *

    * @param  string  $query

    * @return Result from elasticsearch

    */

Kiểu chú thích dài này được gọi là DocBlock, một chú thích nhiều dòng được báo cáo ở trên cùng của việc thực hiện bất kỳ một lớp, giao diện, phương thức, thuộc tính và thuộc tính,. Những bình luận này thường nói với người đọc (nhà phát triển hoặc người dùng cuối) về hoạt động mà mã thực thi, tham số được yêu cầu và dữ liệu được trả về. Bạn có thể thêm thông tin vào DocBlock

Một DocBlock bắt đầu bằng một dấu gạch chéo và hai dấu hoa thị (/ **), nó giống như bắt đầu của một nhận xét nhiều dòng nhưng thêm vào 1 dấu hoa thị nữa, và kết thúc bằng một dấu hoa và dấu gạch . Nó cũng bao gồm các thẻ, chú thích và mô tả để xác định các không gian tên và lớp bổ sung

Tạo tài liệu cho API

DocBlocks rất quan trọng bởi vì chúng được sử dụng bởi gói tạo tài liệu Symfony nổi tiếng được gọi là Sami. Rất phổ biến trong cộng đồng PHP, Sami cũng cung cấp khả năng tạo các mẫu twig mẫu tùy chỉnh và làm việc với các phiên bản tài liệu trên GitHub

Trong bài viết này, tôi sẽ sử dụng dữ liệu Sami và một dự án trên GitHub Đồng bộ hóa dữ liệu Mysql với Elaticsearch để tự động tạo tài liệu

Cài đặt Sami

SSH đến thư mục của dự án sau đó chạy lệnh composer as after

composer require sami/sami

Sau khi cài đặt, bạn có thể kiểm tra xem Sami đã được cài đặt đúng cách và đã sẵn sàng hoạt động hay chưa. Để làm điều này, hãy chạy lệnh sau

$ php vendor/sami/sami/sami.php

Bạn sẽ nhận được đầu ra như sau

Điều này cho thấy rằng Sami đã sẵn sàng để tạo ra tài liệu

Nhân bản ứng dụng GitHub

Gần đây, tôi đã phát hiện ra một gói tuyệt vời là Đồng bộ hóa dữ liệu Mysql với Elaticsearch có nhận xét và Docblocks thích hợp

Để bắt đầu, bạn nên sao chép gói này vào ứng dụng của bạn, sử dụng lệnh sau

$ git clone https://github.com/ahmedkhan847/mysqlwithelasticsearch.git

Nếu bạn xem các tệp trong thư mục src của gói này, bạn sẽ thấy các nhận xét thích hợp được thêm vào tất cả các khối mã. Những khối này giúp Sami hiểu cấu trúc và thuộc tính của các thành phần trong gói

Tạo tệp cấu hình. php

You must make a file config. php trong thư mục cấu hình trong thư mục gốc. Sami đọc tệp này và tạo ra các tệp tài liệu cho phù hợp. Yêu cầu tối thiểu cho quá trình tạo tài liệu là đường dẫn thư mục mà mã được lưu giữ

Đây là những gì để bao gồm trong cấu hình. php

 
return new Sami\Sami('mysqlwithelasticsearch/src/');

Bây giờ chúng ta chạy lệnh sau

$ php vendor/sami/sami/sami.php update config/config.php

Sami sẽ đọc tệp cấu hình và tạo ra hai thư mục trong thư mục gốc của dự án, xây dựng (chứa các tệp đầu ra) và bộ đệm (bộ đệm mẫu twig)

Bây giờ hãy truy cập URL của thư mục bản dựng trên trình duyệt. URL will have format.

composer require sami/sami

2

Bạn sẽ thấy các đầu ra sau đây có chứa tất cả các lớp, không gian tên, phương thức, thuộc tính và các biến được định nghĩa trong mã

Vì vậy, bằng cách sử dụng cấu hình cơ bản, tôi đã tạo ra toàn bộ tài liệu dự án (định dạng đúng) bằng cách sử dụng Sami

You can also expand file config. php bằng cách định nghĩa thêm các cấu hình như trình lặp, tùy chọn và phiên bản cho tài liệu tương thích với Git. Sami sử dụng thành phần Finder của Symfony với các mảng như một tham số

Đây là một cấu hình nâng cao hơn

________số 8

Tôi đã lưu đường dẫn nguồn trong

composer require sami/sami

3, và sau đó trong

composer require sami/sami

4. Bao gồm tất cả các tệp PHP và loại trừ thư mục xây dựng và kiểm tra (do đó chỉ bao gồm các tệp chứa mã). Trong $options có chủ đề mặc định và tiêu đề cho tài liệu. Ngoài ra, nó chứa build_dir cho đầu ra và cache_dir cho twig bộ nhớ đệm

Định cấu hình phiên bản Git

Khi làm việc với các phiên bản trong Git, bạn phải thêm thẻ '%version%'. Để tạo tài liệu cho tất cả các thẻ trong phiên bản 2. 0, các nhánh phụ của nó và nhánh chính, bạn cần chỉ định

composer require sami/sami

5 và

composer require sami/sami

6

/**

    * Search in Elasticsearch.

    *

    * @param  string  $query

    * @return Result from elasticsearch

    */

3

Bây giờ bạn sẽ thấy thư mục bản dựng chứa các thư mục cho mỗi phiên bản

Create Custom Themes (Các chủ đề tùy chỉnh)

Cho đến bây giờ, tôi đang sử dụng chủ đề mặc định. Tuy nhiên, Sami cung cấp sự hoạt động để tạo ra chủ đề của riêng bạn

Đối với điều này, bạn cần phải tạo một chủ đề thư mục trong thư mục gốc và xác định đường dẫn trong tệp cấu hình. php

/**

    * Search in Elasticsearch.

    *

    * @param  string  $query

    * @return Result from elasticsearch

    */

4

Bây giờ để tạo chủ đề mới, bạn cần thêm thư mục vào tên của chủ đề. Mỗi chủ đề chứa một tệp kê khai. yml, normal with after content

/**

    * Search in Elasticsearch.

    *

    * @param  string  $query

    * @return Result from elasticsearch

    */

0

Tùy chỉnh chủ đề sẽ kế thừa các thuộc tính chủ đề mặc định

cuối cùng

Sami làm giảm đáng kể quá trình tạo tài liệu cho API và các dự án PHP ở tất cả các quy định. Với một đơn giản cấu hình, bạn đã hoàn thành nhiệm vụ thực sự mệt mỏi này

Lưu ý rằng Sami không phải là công cụ tạo tài liệu hay tài liệu API REST duy nhất. You can also try phpDocumentor. Tuy nhiên, Sami cung cấp một số tùy chọn nâng cao mà không tìm thấy trong các tùy chọn khác