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
?>
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
*/
?>
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;
?>
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 APIDocBlocks 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
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 GitHubGầ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 //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. phpYou 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