Hướng dẫn how do i run phpdocumentor? - làm cách nào để chạy phpdocumentor?
Cài đặtCó ba cách, được khuyến nghị, để bắt đầu sử dụng PhpDocom số: Show
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ốngNế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.
Độc lập, sử dụng DockerMặ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ẽ đủ: Để 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: Sau khi làm điều đó, bạn chỉ có thể gọi Như một sự phụ thuộc, sử dụng PhiveNếu Phive được cài đặt toàn cầu, bạn có thể chạy lệnh sau: 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 pharBạn có thể tải xuống tệp Phar mới nhất từ https://phpdoc.org/phpdocumentor.phar hoặc một phiên bản cụ thể từ https://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ố: 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: Sau đó, bạn có thể chạy nó trên toàn cầu: Và tiếp theo
Gói: PhpDocumentor HTML_Treemenu Converters CPDF XML_Beautifier Smarty Tutorials/Manuals:Package-level:
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
PhpDocumentor cho người mớibởi Gregory Beaver Mục lục
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ụ PHPDocumentorCó 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 http: //localhost/phpinfo.php Phpinfo.php:
Nế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í đó (http: // localhost/phpDoc).
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, http://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 PhpDocumentor
và 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 http: // 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 phpDocumentorTà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. (adsbygoogle = window.adsbygoogle || []).push({}); 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étBâ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: Tấ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. Tài liệu về các biến toàn cầuLưu ý mã này từ Sample2.php: Trong 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. Thẻ @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 trangCâ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: PhpDocumentor 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: Ví 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.
Viết tài liệu bên ngoài và liên kết đến tài liệu mã nguồnMặ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 Basic usage of phpDocumentor toolBâ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, PHPDocdocBuilder, giao diện web PHPDocum số
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. Làm thế nào để sử dụng PhpDocom số?Việc sử dụng cơ bản của PHPDocomentor là cung cấp vị trí đầu vào bằng cách sử dụng các tùy chọn dòng lệnh (-d cho một thư mục, -f cho một tệp) và bảo nó xuất tài liệu của bạn vào một thư mục theo ý thích của bạn (-T).provide an input location using the command line options (-d for a directory, -f for a file) and tell it to output your documentation to a folder of your liking (-t).
Nhận xét PHPDOC là gì?Các khối PHPDOC là nhận xét mô tả là một phần của mã ứng dụng.Chúng được sử dụng để mô tả phần tử PHP ở vị trí chính xác trong mã xuất hiện phần tử.Khối bao gồm một mô tả ngắn, mô tả dài và thẻ PHPDOC.descriptive comments that are part of the application code. They are used to describe the PHP element in the exact location in the code where the element appears. The block consists of a short description, long description, and phpDoc tags.
Tại sao bạn phải sử dụng cú pháp PHPDOC để mã tài liệ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ễ hiểu về mã của bạn - tuần, tháng và thậm chí nhiều năm sau khi bạn viết nó.you can make it easy for others (and yourself) to understand your code – weeks, months, and even years after you've written it. |
