Cài đặt
Có ba cách, được khuyến nghị, để bắt đầu sử dụng PhpDocom số:
- Kéo hình ảnh Docker được xây dựng sẵn của chúng tôi [khuyến nghị].
- Sử dụng Phive để cài đặt phpDocom số làm phụ thuộc vào dự án của bạn.
- Tải xuống tệp Phar và đặt nó vào vị trí thích của bạn.
Cái nào bạn sử dụng phụ thuộc vào việc bạn muốn sử dụng Docker hay không, hoặc bao gồm PhpDocomentor trong thiết lập dự án của bạn.
yêu cầu hệ thống
Nếu bạn đang sử dụng container Docker chính thức hoặc hành động GitHub, bạn không cần phải lo lắng về điều này và có thể trực tiếp bỏ qua chương độc lập, sử dụng Docker.
PhpDocumentor có một số phụ thuộc vào các gói phần mềm khác. Vui lòng đảm bảo rằng bạn có những thứ này có sẵn trước khi cài đặt PHPDocumentor.
- Php 7.4.0 trở lên
- Tiện ích mở rộng PHP MBString
- GraphViz [Tùy chọn]
- Plantuml_ [tùy chọn]
Độc lập, sử dụng Docker
Mặc dù không phải là một phương thức cài đặt thực tế; Phương pháp dễ nhất để sử dụng phpDocom số, nếu bạn đã cài đặt Docker, là sử dụng hình ảnh Docker của chúng tôi. Hình ảnh Docker đi kèm với tất cả các phụ thuộc được cài đặt sẵn để bạn không phải cài đặt các địa phương này.
Để chạy phpDocom số bằng Docker, điều sau đây sẽ đủ:
$ docker run --rm -v "$[pwd]:/data" "phpdoc/phpdoc:3"
Để thuận tiện, bạn có thể bí danh lệnh này để bạn có thể sử dụng nó từ bất kỳ thư mục nào một cách dễ dàng:
$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
Sau khi làm điều đó, bạn chỉ có thể gọi
$ phive install phpDocumentor
5 từ bất kỳ vị trí nào. Điều này cũng có thể giúp tuân theo các ví dụ trong tài liệu này vì chúng tôi giả sử bạn có một lệnh gọi là $ phive install phpDocumentor
5 có sẵn trên toàn cầu.Như một sự phụ thuộc, sử dụng Phive
Nếu Phive được cài đặt toàn cầu, bạn có thể chạy lệnh sau:
$ phive install phpDocumentor
Khi bạn chạy lệnh, PHPDocomentor sẽ được cài đặt và nó có thể được thực thi trực tiếp.
Để biết thêm thông tin về Phive, hãy xem trang web Phive.
Độc lập, tải xuống một phar
Bạn có thể tải xuống tệp Phar mới nhất từ //phpdoc.org/phpdocumentor.phar hoặc một phiên bản cụ thể từ //github.com/phpdocumentor/phpdocumentor/releases.
Tệp Phar có thể được sử dụng bằng cách gọi trực tiếp PHP và cung cấp tệp Phar làm tham số:
$ php phpDocumentor.phar -d . -t docs/api
Hoặc, trên Mac và Linux, bạn có thể đánh dấu nó là thực thi và di chuyển nó vào thư mục bin của bạn:
$ chmod +x phpDocumentor.phar
$ mv phpDocumentor.phar /usr/local/bin/phpDocumentor
Sau đó, bạn có thể chạy nó trên toàn cầu:
$ phpDocumentor -d . -t docs/api
Và tiếp theo
- Docblock là gì? - Cách nhanh chóng bắt đầu sử dụng PhpDocom số.
- Cấu hình - Tùy chọn cấu hình nâng cao.
Gói: PhpDocumentor HTML_Treemenu Converters CPDF XML_Beautifier Smarty
phpDocumentor
HTML_TreeMenu
Converters
Cpdf
XML_Beautifier
Smarty
Tutorials/Manuals:Package-level:
Package-level:
- Hướng dẫn của PhpDocumentor để tạo tài liệu tuyệt vời
- PhpDocumentor QuickStart
- Mã nguồn cho Sample1.php
- Mã nguồn cho Sample2.php
- Mã nguồn cho Sample3.php
- Hướng dẫn PHPDocumentor
- Các yếu tố PHP có thể ghi được
- Hướng dẫn PHPDocumentor
- Hướng dẫn sử dụng PHPDocumentor
- Thẻ PHPDocumentor
- @abstract
- @access
- @author
- @category
- @copyright
- @deprecated
- @example
- @final
- @filesource
- @global
- @ignore
- @internal
- @license
- @link
- @method
- @name
- @package
- @param
- @property
- @return
- @see
- @since
- @static
- @staticvar
- @subpackage
- @todo
- @tutorial
- @Uses
- @var
- @version
- Các thẻ nội tuyến phpDocumentor
- nội tuyến {@example}
- nội tuyến {@id}
- nội tuyến {@Internal}}
- nội tuyến {@InHeritDoc}
- nội tuyến {@link}
- nội tuyến {@source}
- nội tuyến {@toc}
- nội tuyến {@tutorial}
- Thẻ PHPDocumentor
- PhpDocumentor QuickStart
Files:
subpackage DescHTML
subpackage DocBlockTags
subpackage Errors
subpackage InlineTags
subpackage Links
subpackage ParserData
subpackage ParserDocBlock
subpackage ParserElements
subpackage Parsers
subpackage setup
subpackage Tutorial
subpackage WordParsers
Trước | Tiếp theo |
PhpDocumentor cho người mới
bởi Gregory Beaver
Mục lục
- PhpDocum số là gì? Nó có thể làm gì? Cài đặt & nbsp; & nbsp; & nbsp; tải xuống từ pear.php.net hoặc nguồn ; & nbsp; & nbsp; & nbsp; & nbsp; Công cụ & nbsp; & nbsp; & nbsp; công cụ dòng lệnh, phpdoc & nbsp; & nbsp; & nbsp; docBuilder, giao diện web PHPDocumentor
Installation
Download from Pear.Php.net or Sourceforge.net
Installation through PEAR
How to document your code for use with phpDocumentor
Documenting your PHP source code with comments
Documenting global variables
Page-level DocBlock warnings
Writing external documentation and linking to source code documentation
Basic usage of phpDocumentor tool
Command-line tool, phpdoc
docbuilder, the phpDocumentor web interface
PhpDocum số là gì? Nó có thể làm gì?
PHPDocumentor là một công cụ được viết trong PHP được thiết kế để tạo tài liệu hoàn chỉnh trực tiếp từ cả mã PHP và tài liệu bên ngoài. Sự thật là, mã nguồn PHP rất sáng suốt, nó thực tế có thể đóng vai trò là tài liệu riêng của nó. PhpDocum số tham gia vào thực tế này bằng cách phân tích tất cả các loại cấu trúc logic đã được tìm thấy trong PHP, chẳng hạn như tệp, lớp, chức năng, xác định hằng số, biến toàn cầu và các biến/phương thức lớp và tổ chức chúng thành định dạng thủ công truyền thống. Ngoài ra, mới với phiên bản 1.3.0, các yếu tố mã nguồn được giới thiệu trong PHP 5 [hằng số lớp, giao diện và các yếu tố khác] cũng có thể được phân tích cú pháp, nếu phpDocom số được chạy qua PHP 5. đầu ra có thể được tạo để duyệt web từ xa, in, in, và tích hợp vào các hệ thống trợ giúp IDE thông qua các bộ chuyển đổi cho HTML, PDF và CHM [tệp trợ giúp Windows].
PhpDocumentor tạo tài liệu định dạng thủ công bằng cách đọc nó từ các bình luận PHP đặc biệt được gọi là docblocks. DocBlocks là nơi bạn là tác giả của một dự án phần mềm nên ghi lại thông tin hữu ích có thể được sử dụng bởi những người khác [hoặc tương lai của bạn] để xác định cách sử dụng và mở rộng gói PHP của bạn.
Mặc dù khả năng thêm tài liệu cô đọng trong mã nguồn là rất cần thiết, nhưng nó không thể thay thế tầm quan trọng của tài liệu dài dòng không có trong mã nguồn, chẳng hạn như hướng dẫn sử dụng hoặc hướng dẫn như tài liệu bạn đang đọc bây giờ. Nếu văn bản bạn thấy ở đây được đặt trong mã nguồn cho PhpDocom số, nó sẽ phục vụ ít mục đích hữu ích, làm lộn xộn mã và khó định vị. Tuy nhiên, khả năng siêu liên kết giữa tài liệu trong mã nguồn và tài liệu bên ngoài là rất cần thiết. Tài liệu bên ngoài cho chức năng FOO phải có khả năng tham chiếu tài liệu trong mã được tạo và với PhpDocomeror điều này cuối cùng là có thể. Để tìm hiểu thêm, hãy đọc về các hướng dẫn của PhpDocom số.
Cài đặt Cách ghi lại mã của bạn để sử dụng với sử dụng PHPDocumentOrbasic của công cụ PHPDocumentor
Có hai phương pháp cài đặt chính thức cho PhpDocom số. Đầu tiên là thông qua việc tải xuống và trích xuất một trong những tài liệu lưu trữ có sẵn có thể tải xuống thông qua Pear.php.net và SourceForge.net, và cái còn lại là thông qua Trình cài đặt PEAR. Có kế hoạch cho một nhiệm vụ Phing và phân phối thông qua các khung cài đặt mới và đầy hứa hẹn khác như Trình cài đặt ZZ/OSS. Tuy nhiên, chỉ có hai phương thức cài đặt chính thức được hỗ trợ bởi các nhà phát triển của PHPDocomeror.
Tải xuống từ Pear.php.net hoặc SourceForge.net
Để cài đặt phpDocumentor từ .zip hoặc tarball được tải xuống trực tiếp từ pear.php.net hoặc nguồn quyết định].
Nếu bạn muốn sử dụng giao diện dòng lệnh, giải nén kho lưu trữ vào bất kỳ thư mục nào, giả sử/home/myuser/phpDoc hoặc c: \ program files \ phpDoc và thêm thư mục đó vào câu lệnh path path của bạn. Để sử dụng, hãy chạy lệnh "PHPDOC". Trong Windows, bạn sẽ cần chỉnh sửa tệp PHPDoc.bat và thay đổi dòng đầu tiên thành đường dẫn của phiên bản CLI của PHP [thường là C: \ Php4 \ CLI \ php.exe theo mặc định].
Để sử dụng giao diện web, bạn phải có một máy chủ web như Apache được cài đặt và phải có PHP SAPI làm việc cho máy chủ đó. Để kiểm tra, hãy lưu mã bên dưới dưới dạng phpinfo.php trong root tài liệu của bạn và duyệt đến //localhost/phpinfo.php
Phpinfo.php:
$ phive install phpDocumentor
7Nếu bạn thấy một màn hình màu tím đẹp của thông tin PHP, thì thiết lập PHP của bạn đang hoạt động. Để sử dụng giao diện web của PHPDocumentor, chỉ cần giải nén kho lưu trữ vào một thư mục con của gốc tài liệu của bạn [như PHPDOC] và duyệt đến vị trí đó [ // localhost/phpDoc].
Một trình duyệt hỗ trợ JavaScript như Netscape, Mozilla, Internet Explorer, Opera hoặc Konqueror được yêu cầu để xem giao diện web mới hơn. Nếu bạn muốn sử dụng trình duyệt không phải JavaScript như Links/Lynx, hãy sử dụng giao diện web cũ, phpDoc.php tại //localhost/phpdoc/phpdoc.php. |
Cài đặt thông qua lê
Để cài đặt PHPDocomentor thông qua PEAR, trước tiên bạn phải có một cài đặt hoạt động của lê. Hướng dẫn cài đặt PEAR đúng cách được đặt tại trang web Pear chính thức, //pear.php.net. Các nhà phát triển PHPDocumentor không hỗ trợ các vấn đề cài đặt với PEAR, thay vào đó tìm kiếm sự giúp đỡ từ các nhà phát triển lê.
Cài đặt PHPDocomentor để sử dụng trên dòng lệnh rất đơn giản. Đơn giản chỉ cần chạy:
$ pear install PhpDocumentorvà sau đó bạn có quyền truy cập đầy đủ vào lệnh PHPDOC, cả trong Windows và Unix, mà không cần cấu hình thêm.
Để cài đặt PHPDocomentor để sử dụng giao diện web, trước tiên bạn phải thay đổi một trong các biến cấu hình của Pear, Data_DIR, thành một thư mục phụ của root tài liệu Web Server của bạn. Cách đơn giản nhất để làm điều này là thông qua giao diện dòng lệnh của Pear với lệnh:
$ pear config-set data_dir /path/to/document_root/pear
Cấu hình giá trị này thông qua giao diện web cũng đơn giản. Nhấp vào biểu tượng cấu hình trong khung bên trái và nhập vào đường dẫn trong hộp văn bản data_dir.
Khi cấu hình này hoàn tất, chỉ cần cài đặt phpDocomentor như được mô tả trong đoạn thứ hai ở trên và sau đó bạn có thể duyệt đến // localhost/pear/phpdocumentor để có quyền truy cập vào giao diện web. Khi bước cấu hình này đã được thực hiện, không bao giờ có bất kỳ nhu cầu nào thay đổi và bạn có thể dễ dàng nâng cấp lên các phiên bản PHPDocum số trong tương lai bằng cách sử dụng lệnh nâng cấp của Pear.
How to document your code for use with phpDocumentor
Tài liệu về các dự án mã của bạn là đơn giản và trực quan đối với hầu hết các phần. Trước khi bạn bắt đầu, bạn có thể muốn tải xuống dự án tài liệu mẫu và thử chạy phpDocumentor trên chúng khi bạn đọc cùng, được tìm thấy tại mã nguồn cho Sample1.php, mã nguồn cho Sample2.php, mã nguồn cho Sample3.php hoặc được tìm thấy được gói trong Các hướng dẫn/ thư mục phân phối PhpDocomer của bạn. Trước khi phân tích cú pháp, sao chép các ví dụ vào thư mục khác.
Trước hết, chạy phpDocom số trên tệp trống mẫu1.php. Nếu bạn đang sử dụng giao diện dòng lệnh, hãy chạy lệnh này từ thư mục hướng dẫn/mẫu:
$ phpdoc -o HTML:frames:earthli -f sample1.php -t docs
Nếu bạn đang sử dụng giao diện web, hãy nhấp vào tab "Tệp" và nhập đường dẫn đầy đủ đến hướng dẫn/sample/sample1.php. Sau đó nhấp vào tab "Đầu ra" và nhập đường dẫn đầy đủ đến các hướng dẫn/mẫu/tài liệu và cuối cùng nhấp vào nút "Tạo" ở góc dưới bên phải.
Với trình duyệt Web, hãy mở tệp hướng dẫn/mẫu/tài liệu/index.html mới được tạo và bạn sẽ thấy mảng thông tin phong phú mà PhpDocumentor có thể phân tích từ mã nguồn ngay cả khi không có bất kỳ nhận xét tài liệu nào. Thông tin kế thừa, đa hình và hằng số đều được công nhận tự động. Lưu ý rằng yếu tố duy nhất không được ghi lại tự động là biến toàn cầu - để thực hiện việc này, bạn phải sử dụng một tài liệu PHPDocumentor như được mô tả trong phần tiếp theo của hướng dẫn sử dụng QuickStart này. Cũng lưu ý rằng mặc dù bao gồm_once chỉ định một tệp trong bao gồm_path, phpDocomentor sẽ không tự động phân tích sample2.php, bạn phải chỉ định thủ công các tệp hoặc thư mục để phân tích cú pháp.
Nếu bạn cảm thấy thích phiêu lưu, hãy thử nghiệm các tùy chọn phân tích cú pháp có sẵn và phân tích các tệp mẫu một vài lần để xem chúng ảnh hưởng đến đầu ra tài liệu như thế nào. Để tìm ra các tùy chọn trong giao diện dòng lệnh, hãy loại
$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
0Ghi lại mã nguồn PHP của bạn với nhận xét
Bây giờ Mở Sample2.php. Đây là nội dung mã tương tự như Sample1.php, nhưng nó chứa một loạt đầy đủ các nhận xét của PhpDocom số. Lưu ý rằng mọi nhận xét của DocBlock là một nhận xét kiểu C với hai dấu sao hàng đầu [*], như vậy:
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
1Tất cả các ý kiến khác bị bỏ qua bởi trình phân tích cú pháp tài liệu. Lưu ý rằng mặc dù hầu hết các tài liệu là tiếng Anh đơn giản, có một vài ký tự "@" nổi xung quanh mã nguồn. Biểu tượng này được sử dụng để chuyển một lệnh đặc biệt cho trình phân tích cú pháp và được gọi là thẻ. Nếu biểu tượng ở đầu một dòng, thì đó là một thẻ tiêu chuẩn và nếu nó được đặt trong {dấu ngoặc xoăn}, thì đó là một thẻ nội tuyến. Bạn có thể đọc thêm về các thẻ tại các thẻ phpDocumentor và các thẻ nội tuyến phpDocumentor.
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
2 Tài liệu về các biến toàn cầu
Lưu ý mã này từ Sample2.php:
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
3Trong phân khúc này, chúng ta có thể thấy hai thẻ quan trọng được sử dụng để ghi lại các biến toàn cầu. Thẻ @Global được sử dụng để nói với trình phân tích cú pháp cách tìm khai báo biến toàn cầu. Không có thẻ này, không có tài liệu nào được tạo cho $ _Myvar. Thẻ @Global có thể có nhiều biểu mẫu - chắc chắn chỉ định loại và tên toàn cầu, không có mô tả hoặc trình phân tích cú pháp sẽ tạo cảnh báo và không ghi lại biến.
Bây giờ, Parse Sample3.php và quan sát các tài liệu được tạo. Thẻ @NAME được sử dụng để nói với trình phân tích cú pháp làm thế nào biến toàn cầu sẽ được tham chiếu bởi một câu lệnh toàn cầu trong một hàm.
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
4Thẻ @Global ở đây sẽ liên kết thông tin với các câu lệnh toàn cầu được khai báo trong cơ quan chức năng theo cùng thứ tự tuyên bố của họ.
Cảnh báo tài liệu cấp trang
Câu hỏi thường gặp nhất về việc sử dụng PhpDocom số liên quan đến các cảnh báo về các tài liệu cấp trang. Phần này sẽ trả lời bất kỳ câu hỏi về cảnh báo này một lần và mãi mãi.
PhpDocumentor tổ chức các yếu tố thủ tục và các lớp thành các nhóm đặc biệt được gọi là các gói. Trong các phiên bản trước của PHPDocomentor, nếu gói không được chỉ định rõ ràng bằng cách sử dụng thẻ @package, chương trình sẽ đưa ra một dự đoán có giáo dục về việc gói một phần tử nguồn nào thuộc về.
Theo thời gian, rõ ràng là trong nhiều trường hợp, các yếu tố nguồn được nhóm không chính xác thành một gói do sử dụng PhpDocum số phỏng đoán. Cuối cùng, quyết định đã được đưa ra để yêu cầu thẻ @package rõ ràng và đưa ra cảnh báo bất cứ khi nào thẻ này bị thiếu trong phần tử nguồn cấp cao nhất.
Sự nhầm lẫn lớn nhất đến từ việc tài liệu của các tập tin. PhpDocumentor tài liệu tất cả các yếu tố nguồn bằng cách đọc tài liệu ngay trước phần tử, như vậy:
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
5PhpDocumentor cũng có thể ghi lại nội dung của một tệp. Nhưng làm thế nào một docblock có thể ngay trước tệp chứa nó? Câu trả lời dễ dàng là giả sử DocBlock đầu tiên trong một tệp ghi lại tệp chứa nó và điều này hoạt động tốt, nhưng có thể lừa dối:
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
6Ví dụ tương tự cho thấy sự mơ hồ - Docblock này có ghi lại lớp học hay tệp không? Để giải quyết sự mơ hồ này, PhpDocomeror sử dụng một thuật toán đơn giản để đưa ra quyết định của mình.
- Nếu tài liệu đầu tiên trong tệp chứa thẻ @package, nó sẽ ghi lại tệp trừ khi nó đi trước khai báo lớp
- Nếu tài liệu đầu tiên trong một tệp trước một tài liệu khác, nó sẽ ghi lại tệp
$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
7$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
8$ phive install phpDocumentor
7$ alias phpdoc="docker run --rm -v $[pwd]:/data phpdoc/phpdoc:3"
9$ phive install phpDocumentor
7$ phive install phpDocumentor
0$ phive install phpDocumentor
7$ phive install phpDocumentor
1$ phive install phpDocumentor
7$ phive install phpDocumentor
2$ phive install phpDocumentor
7$ phive install phpDocumentor
3Viết tài liệu bên ngoài và liên kết đến tài liệu mã nguồn
Mặc dù tài liệu được phân tích trực tiếp từ mã nguồn là rất hữu ích, nhưng nó không thể tự đứng vững. Ngoài ra, tài liệu trong mã thực sự hữu ích phải đủ ngắn gọn để mã không bị che khuất hoàn toàn bởi tài liệu. Tài liệu bên ngoài là phải cho một giải pháp tài liệu đầy đủ. Tuy nhiên, tài liệu bên ngoài phải có khả năng liên kết đến tài liệu nguồn API là hữu ích. Với một tài liệu API thay đổi liên tục, rất dễ dàng để tài liệu bên ngoài trở nên lỗi thời. Ngoài ra, tài liệu bên ngoài phải ở định dạng có thể được chuyển đổi thành các định dạng khác như HTML, PDF và XML.
PhpDocumentor cung cấp một giải pháp đơn giản và thanh lịch cho tất cả các vấn đề này. Tài liệu bên ngoài ở định dạng DocBook có thể dễ dàng chuyển đổi sang các định dạng khác. Sử dụng các thẻ nội tuyến, PhpDocomentor có thể tạo một hướng dẫn nhất quán ở nhiều định dạng khác nhau bằng cách kết hợp đầu ra từ việc phân tích nguồn và phân tích tài liệu bên ngoài. Các từ bạn đọc tại thời điểm này nằm trong một tệp dựa trên tài liệu nằm trong hướng dẫn/phpDocumentor/phpDocumentor.quickStart.pkg
$ phive install phpDocumentor
7$ phive install phpDocumentor
4 Basic usage of phpDocumentor tool
Bây giờ PHPDocomentor đã được cài đặt, làm thế nào bạn có thể sử dụng nó để ghi lại một dự án? Đầu tiên, bạn phải hiểu cách PHPDocomeror chia mã của bạn thành các gói và thanh toán con. Nếu bạn chưa có, bây giờ sẽ là thời điểm tốt để đọc cách ghi lại mã của bạn để sử dụng với phần PHPDocumentor của QuickStart này.
Công cụ dòng lệnh, PHPDoc
docBuilder, giao diện web PHPDocum số
Trước | Lên | Tiếp theo |
Hướng dẫn của PhpDocumentor để tạo tài liệu tuyệt vời | Hướng dẫn của PhpDocumentor để tạo tài liệu tuyệt vời | Mã nguồn cho Sample1.php |
Tài liệu được tạo ra trên Thứ Hai, ngày 11 tháng 3 năm 2019 15:50:04 -0400 bởi PhpDocomentor 1.4.4. Logo Pear Bản quyền © Nhóm PHP 2004.