Hướng dẫn when to use phpdoc? - khi nào nên sử dụng phpdoc?

PhpDocumentor cơ bản

Bắt đầu từ đầu

Quá trình tài liệu bắt đầu với yếu tố cơ bản nhất của PhpDocom số: Khối tài liệu hoặc DocBlock. Một tài liệu cơ bản trông như thế này:Documentation block or DocBlock. A basic DocBlock looks like this:

1. /**

2.  *

3.  */

DocBlock là một bình luận PHP C ++ mở rộng bắt đầu bằng "/**" và có "*" ở đầu mỗi dòng. DocBlocks trước phần tử họ đang ghi lại.

Để ghi lại hàm "foo ()", hãy đặt docblock ngay trước khi khai báo chức năng:

1. /**

2.  * Defies imagination, extends boundaries and saves the world ...all before breakfast!

3.  */

4. function foo()foo()

5. DocBlock là một bình luận PHP C ++ mở rộng bắt đầu bằng "/**" và có "*" ở đầu mỗi dòng. DocBlocks trước phần tử họ đang ghi lại.

6. Bất kỳ dòng nào trong một docblock không bắt đầu với A * sẽ bị bỏ qua.

Để ghi lại hàm "foo ()", hãy đặt docblock ngay trước khi khai báo chức năng:

1. /**

2.  * DocBlock for function foo?

3.  *

4.  * No, this will be for the constant me!

5.  */

6. define('me',2);('me',2);

7. function foo($param = me)foo($param = me)

8. DocBlock là một bình luận PHP C ++ mở rộng bắt đầu bằng "/**" và có "*" ở đầu mỗi dòng. DocBlocks trước phần tử họ đang ghi lại.

9. Bất kỳ dòng nào trong một docblock không bắt đầu với A * sẽ bị bỏ qua.

Để ghi lại hàm "foo ()", hãy đặt docblock ngay trước khi khai báo chức năng:

{

}

• Ví dụ này sẽ áp dụng DocBlock để "Xác định ('Me', 2);" Thay vì "Function foo ()":

• Xác định () các câu lệnh, hàm, lớp, phương thức lớp và vars vars, bao gồm () và các biến toàn cầu đều có thể được ghi lại, xem các yếu tố của mã nguồn có thể được ghi lại

• Docblocks

Một DocBlock chứa ba phân đoạn cơ bản theo thứ tự này:

1. /**

2.  * return the date of Easter

3.  * 

4.  * Using the formula from "Formulas that are way too complicated for anyone to

5.  * ever understand except for me" by Irwin Nerdy, this function calculates the

6.  * date of Easter given a date in the Ancient Mayan Calendar, if you can also

7.  * guess the birthday of the author.

8.  */

DocBlock là một bình luận PHP C ++ mở rộng bắt đầu bằng "/**" và có "*" ở đầu mỗi dòng. DocBlocks trước phần tử họ đang ghi lại.

1. /**

2.  * Short desc

3.  *

4.  * Long description first sentence starts here

5.  * and continues on this line for a while

6.  * finally concluding here at the end of

7.  * this paragraph

8.  *

9.  * The blank line above denotes a paragraph break

10.  */

DocBlock là một bình luận PHP C ++ mở rộng bắt đầu bằng "/**" và có "*" ở đầu mỗi dòng. DocBlocks trước phần tử họ đang ghi lại.

1. /**

2.  * Short desc

3.  *

4.  * Long description first sentence starts here

5.  * and continues on this line for a while

6.  * finally concluding here at the end of

7.  * this paragraph

8.  * This text is completely ignored! it is not enclosed in p tags

9.  * This is a new paragraph

10.  */

DocBlock là một bình luận PHP C ++ mở rộng bắt đầu bằng "/**" và có "*" ở đầu mỗi dòng. DocBlocks trước phần tử họ đang ghi lại.

1. /**

2.  * 

3.  * Short desc is only to the first period.

4.  * This means a sentence like:

5.  * "Parses Mr./Mrs. out of $_GET." will

6.  * parse a short description of "Parses Mr."

7.  * which is rather silly.  Long description is

8.  * the entire DocBlock description including the

9.  * Short desc, and paragraphs begin where p is like:

10.  * 

11.  * The p above denotes a paragraph break

12.  */

PhpDocumentor sẽ chuyển đổi tất cả khoảng trắng thành một không gian duy nhất trong mô tả dài, sử dụng các đoạn vỡ đoạn để xác định Newlines, hoặc, như đã thảo luận trong phần tiếp theo.

DOCBLOCK Mô tả chi tiết

Kể từ PhpDocumentor 1.2.0, mô tả dài và ngắn của docblock được phân tích cú pháp cho một vài thẻ HTML chọn định dạng bổ sung. Do tính chất của đầu ra của PhpDocomer là nhiều định dạng, HTML thẳng không được phép trong một tài liệu và sẽ được chuyển đổi thành văn bản thuần túy bởi tất cả các bộ chuyển đổi trừ khi đó là một trong những thẻ này:

• - Nhấn mạnh/Văn bản táo bạo

• - Sử dụng cái này để bao quanh mã PHP, một số bộ chuyển đổi sẽ làm nổi bật nó

• - Break Line Break, có thể bị bỏ qua bởi một số bộ chuyển đổi

• - in nghiêng/đánh dấu là quan trọng

• - biểu thị màn hình đầu vào/màn hình bàn phím

• - Liệt kê mục

• -- danh sách được yêu cầu

• - nếu được sử dụng để gửi kèm tất cả các đoạn văn, nếu không nó sẽ được coi là văn bản

• - Bảo tồn độ ngắt dòng và khoảng cách, và giả sử tất cả các thẻ là văn bản (như CDATA của XML)

• -biểu thị mẫu hoặc ví dụ (không phải PHP)

• - Danh sách không có thứ tự

• - biểu thị một tên biến

"    "

Đối với trường hợp hiếm hoi khi văn bản "" là cần thiết trong một tài liệu, hãy sử dụng dấu phân cách kép như trong. PhpDocumentor sẽ tự động dịch nó sang văn bản vật lý "".

Tương tự, nếu bạn cần một "@" thực tế trong các phần mô tả của Docblock, bạn nên cẩn thận để đảm bảo đó không phải là ký tự đầu tiên trên một dòng, hoặc nếu không thì thoát nó ("\@") để tránh nó được hiểu là một Điểm đánh dấu thẻ PHPDocumentor.

1. /**

2.  * Demonstrate an @include file

3.  * line in a code block:

4.  *

5.  * 

6. & nbsp;*& nbsp; \@bao gồm & nbsp; somefile.php

7.  * 

8.  */

Điều này sẽ phân tích như thể nó là:

1. /**

2.  * Demonstrate an @include file

3.  * line in a code block:

4.  *

5.  * 

6.  * @include somefile.php@include somefile.php

7.  *  

8.  */

Điều này sẽ phân tích như thể nó là: If you need to use the closing comment "*/" in a DocBlock, use the special escape sequence "{@*}." Here's an example:

1. /**

2.  * Simple DocBlock with a code example containing a docblock

3.  *

4.  * 

5.  *  /**

6.  *   * My sample DocBlock in code

7.  *   {@*} 

8.  * 

9.  */

Điều này sẽ phân tích như thể nó là:

1. /**

2.  * Simple DocBlock with a code example containing a docblock

3.  *

4.  * 

5.  *  /**

6.  *   * My sample DocBlock in code

7.  *   */

9. * code>

10. & nbsp;*& nbsp; \@bao gồm & nbsp; somefile.php

Điều này sẽ phân tích như thể nó là: The phpEdit tool supports very clever list extraction from DocBlocks, and now phpDocumentor supports the same cleverness. This example:

1. /**

2.  * Simple DocBlock with simple lists

3.  *

4.  * Here's a simple list:

5.  * - item 1

6.  * - item 2, this one

7.  *   is multi-line

8.  * - item 3

9.  * end of list.  Next list is ordered

10.  * 1 ordered item 1

11.  * 2 ordered item 2

12.  * end of list. This is also ordered:

13.  * 1. ordered item 1

14.  * 2. ordered item 2

15.  */

& nbsp;*& nbsp; \@bao gồm & nbsp; somefile.php

1. /**

2.  * Simple DocBlock with screwy lists

3.  *

4.  * +not a list at all, no space

5.  * Here's 3 lists!

6.  * - item 1

7.  *  - item 2, this one

8.  *   is multi-line

9.  *- item 3

10.  */

Một lần nữa, bạn phải xếp hàng các trình lặp danh sách trong cùng một cột dọc để các mục danh sách đó được coi là "trên cùng một danh sách". Ngoài ra, bạn không thể tạo danh sách lồng nhau bằng cách sử dụng trình lặp danh sách đơn giản ... làm như vậy có nghĩa là nó không còn là danh sách "đơn giản"! Thay đổi khoảng cách của các trình lặp danh sách không tạo ra việc làm tổ của các danh sách ... nó chỉ bắt đầu các danh sách đơn giản mới. Nếu bạn đặc biệt cần một danh sách lồng nhau, bạn phải sử dụng các thẻ danh sách (,):

1. /**

2.  * DocBlock with nested lists

3.  *

4.  * Here's the "complex" list:

5.  * 

6.  * outer item 1

7.  * outer item 2, this one

8.  *   is multi-line

9.  * item 3 is a nested inner list

10.  * 

11.  * inner item 1

12.  * inner item 2

13.  * 

14.  * outer item 4

15.  * 

16.  */

Trong một số trường hợp, mô tả văn bản trong thẻ Doc có thể chứa một danh sách, có thể đơn giản hoặc phức tạp. Lưu ý rằng một dòng tiêu đề là cần thiết, với chính các mục trong danh sách bắt đầu trên dòng tiếp theo:

1. /**

2.  * DocBlock with nested lists

3.  * in the tag descriptions

4.  * @todo My Simple TODO List@todo My Simple TODO List

5.  *     - item 1

6.  *     - item 2

7.  *     - item 3

8.  * @todo My Complex TODO List@todo My Complex TODO List

9.  *     

10.  *       item 1.0

11.  *       item 2.0

12.  *       item 3.0

13.  *         

14.  *           item 3.1

15.  *           item 3.2

16.  *         

17.  *       item 4.0

18.  *     

19.  */

Danh sách được gắn thẻ luôn là một tùy chọn mạnh mẽ hơn và có thể dự đoán được để bạn sử dụng. Các danh sách đơn giản là thuận tiện, nhưng nếu bạn thấy mình đang cố gắng uốn cong một danh sách đơn giản để hiển thị một cách nhất định trong các tài liệu được tạo của bạn, bạn có thể được phục vụ tốt hơn bằng cách chuyển sang danh sách được gắn thẻ thay thế.

Để biết thông tin chuyên sâu về cách PhpDocomeror phân tích trường mô tả, hãy xem Parserdesccleanup.inc

Mẫu DocBlock

Mới cho phiên bản 1.2.0, PHPDocomeror hỗ trợ việc sử dụng các mẫu docblock. Mục đích của một mẫu docblock là để giảm gõ dự phòng. Chẳng hạn, nếu một số lượng lớn các biến lớp là riêng tư, người ta sẽ sử dụng mẫu DocBlock để đánh dấu chúng là riêng tư. Các mẫu docblock chỉ đơn giản là tăng thêm bất kỳ tài liệu bình thường nào được tìm thấy trong khối mẫu.

Một mẫu docblock được phân biệt với một tài liệu bình thường bằng tiêu đề của nó. Đây là mẫu DocBlock cơ bản nhất:

1. /**#@+

2.  *

3.  */

Văn bản đánh dấu đây là mẫu DocBlock là "/**#@+" - Tất cả 6 ký tự phải có mặt. Các mẫu docblock được áp dụng cho tất cả các yếu tố có thể ghi lại cho đến khi điểm đánh dấu mẫu kết thúc:

1. /**#@-*/

Lưu ý rằng tất cả 8 ký tự phải xuất hiện dưới dạng "/**#@-*/" Để PhpDocomentor nhận ra chúng là một mẫu. Dưới đây là một ví dụ về mẫu docblock hoạt động:

1. class BobBob

2. {

3. // beginning of docblock template area

4. /**#@+

5.      * @access private

6.      * @var string

7.      */

8. var $_var1 = 'hello';$_var1 = 'hello';

9. var $_var2 = 'my';$_var2 = 'my';

10. var $_var3 = 'name';$_var3 = 'name';

11. var $_var4 = 'is';$_var4 = 'is';

12. var $_var5 = 'Bob';$_var5 = 'Bob';

13. var $_var6 = 'and';$_var6 = 'and';

14. var $_var7 = 'I';$_var7 = 'I';

15. /**

16.      * Two words

17.      */

18. var $_var8 = 'like strings';$_var8 = 'like strings';

19. /**#@-*/

20. var $publicvar = 'Lookee me!';$publicvar = 'Lookee me!';

21. Lưu ý rằng tất cả 8 ký tự phải xuất hiện dưới dạng "/**#@-*/" Để PhpDocomentor nhận ra chúng là một mẫu. Dưới đây là một ví dụ về mẫu docblock hoạt động:

{

1. class BobBob

2. {

3. // beginning of docblock template area

4. /**

5.      * @access private@access private

6.      * @var string @var string 

7.      */

8. var $_var1 = 'hello';$_var1 = 'hello';

9. /**

10.      * @access private@access private

11.      * @var string @var string 

12.      */

13. var $_var2 = 'my';$_var2 = 'my';

14. /**

15.      * @access private@access private

16.      * @var string @var string 

17.      */

18. var $_var3 = 'name';$_var3 = 'name';

19. /**

20.      * @access private@access private

21.      * @var string @var string 

22.      */

23. var $_var4 = 'is';$_var4 = 'is';

24. /**

25.      * @access private@access private

26.      * @var string @var string 

27.      */

28. var $_var5 = 'Bob';$_var5 = 'Bob';

29. /**

30.      * @access private@access private

31.      * @var string @var string 

32.      */

33. var $_var6 = 'and';$_var6 = 'and';

34. /**

35.      * @access private@access private

36.      * @var string @var string 

37.      */

38. var $_var7 = 'I';$_var7 = 'I';

39. /**

40.      * Two words

41.      * @access private@access private

42.      * @var string @var string 

43.      */

44. var $_var8 = 'like strings';$_var8 = 'like strings';

45. var $publicvar = 'Lookee me!';$publicvar = 'Lookee me!';

46. }

Lưu ý rằng đối với $ _VAR8, mẫu docblock được hợp nhất với DocBlock.Các quy tắc hợp nhất rất đơn giản:

• Mô tả dài của mẫu DocBlock được thêm vào phía trước của mô tả dài.Các mô tả ngắn bị bỏ qua.

• Tất cả các thẻ được hợp nhất từ mẫu docblock

Tags

Thẻ là các từ đơn được tiền tố bởi biểu tượng "@".Tags thông báo cho PhpDocumentor cách trình bày thông tin và sửa đổi hiển thị tài liệu.Tất cả các thẻ là tùy chọn, nhưng nếu bạn sử dụng thẻ, chúng có các yêu cầu cụ thể để phân tích đúng cách.

Một danh sách tất cả các thẻ có thể có trong PhpDocom số theo sau:

1. /**

2.  * The short description

3.  *

4.  * As many lines of extendend description as you want {@link element}{@link element}

5.  * links to an element

6.  * {@link http://www.example.com Example hyperlink inline link} links to{@link http://www.example.com Example hyperlink inline link} links to

7.  * a website. The inline

8.  * source tag displays function source code in the description:

9.  * {@source } {@source } 

10.  * 

11.  * In addition, in version 1.2+ one can link to extended documentation like this

12.  * documentation using {@tutorial phpDocumentor/phpDocumentor.howto.pkg}{@tutorial phpDocumentor/phpDocumentor.howto.pkg}

13.  * In a method/class var, {@inheritdoc may be used to copy documentation from}{@inheritdoc may be used to copy documentation from}

14.  * the parent method

15.  * {@internal {@internal 

16.  * This paragraph explains very detailed information that will only

17.  * be of use to advanced developers, and can contain

18.  * {@link http://www.example.com Other inline links!} as well as text}}}}

19.  *

20.  * Here are the tags:

21.  *

22.  * @abstract@abstract

23.  * @access       public or private@access       public or private

24.  * @author       author name @author       author name <[email protected]>

25.  * @copyright    name date@copyright    name date

26.  * @deprecated   description@deprecated   description

27.  * @deprec       alias for deprecated@deprec       alias for deprecated

28.  * @example      /path/to/example@example      /path/to/example

29.  * @exception    Javadoc-compatible, use as needed@exception    Javadoc-compatible, use as needed

30.  * @global       type $globalvarname @global       type $globalvarname 

31.    or

32.  * @global       type description of global variable usage in a function@global       type description of global variable usage in a function

33.  * @ignore@ignore

34.  * @internal     private information for advanced developers only@internal     private information for advanced developers only

35.  * @param        type [$varname] description@param        type [$varname] description

36.  * @return       type description@return       type description

37.  * @link         URL@link         URL

38.  * @name         procpagealias@name         procpagealias

39.    or

40.  * @name         $globalvaralias@name         $globalvaralias

41.  * @magic        phpdoc.de compatibility@magic        phpdoc.de compatibility

42.  * @package      package name@package      package name

43.  * @see          name of another element that can be documented,@see          name of another element that can be documented,

44.  *                produces a link to it in the documentation

45.  * @since        a version or a date@since        a version or a date

46.  * @static@static

47.  * @staticvar    type description of static variable usage in a function@staticvar    type description of static variable usage in a function

48.  * @subpackage    sub package name, groupings inside of a project@subpackage    sub package name, groupings inside of a project

49.  * @throws       Javadoc-compatible, use as needed@throws       Javadoc-compatible, use as needed

50.  * @todo         phpdoc.de compatibility@todo         phpdoc.de compatibility

51.  * @var        type    a data type for a class variable@var        type    a data type for a class variable

52.  * @version    version@version    version

53.  */

54. function if_there_is_an_inline_source_tag_this_must_be_a_function()if_there_is_an_inline_source_tag_this_must_be_a_function()

55. {

56. // ...

57. }

Ngoài ra, các hướng dẫn cho phép hai thẻ nội tuyến bổ sung: {@ID}, được sử dụng để cho phép liên kết trực tiếp với các phần trong hướng dẫn và {@toc}, được sử dụng để tạo bảng nội dung từ {@Id} s trong tệp. Hãy nghĩ về {@ID} Giống như thẻ HTML, nó phục vụ cùng một chức năng.

Xem nội tuyến {@ID} và nội tuyến {@toc} để biết thông tin chi tiết

Trong ví dụ dưới đây, {@ID} được sử dụng để đặt tên cho refsect1 "mySection" và refsect2 "mySection.MysubSection" - Lưu ý rằng các phần phụ kế thừa ID của phần mẹ.

Để có cái nhìn sâu sắc về các thẻ PHPDocom số, hãy đọc các thẻ PHPDocumentor và để xem sâu các thẻ nội tuyến, hãy đọc các thẻ nội tuyến phpDocumentor.

Documenting your PHP project

Nơi để bắt đầu

Trước khi bạn bắt đầu ghi lại dự án PHP của mình, bạn có thể muốn thử chạy thử trên mã nguồn không có giấy tờ của mình để xem loại thông tin nào PHPDocomentor sẽ tự động trích xuất từ ​​mã nguồn. PhpDocumentor được thiết kế để thực hiện nhiệm vụ ghi lại tối thiểu. Điều này có nghĩa là công việc ít hơn, và tài liệu cập nhật tốt hơn với ít nỗ lực hơn trước đây.

Các yếu tố của mã nguồn có thể được ghi lại

Chia các dự án thành các gói

Để hiểu vai trò của các gói và cách sử dụng @package, điều quan trọng là phải biết logic đằng sau bao bì trong PHP. Cuộc tìm kiếm lập trình có cấu trúc đã dẫn đến việc phát minh ra các chức năng, sau đó là các lớp và cuối cùng là các gói. Theo truyền thống, một mô-đun phần mềm có thể sử dụng lại là một tập hợp các biến, hằng số và các hàm có thể được sử dụng bởi một gói phần mềm khác. PHP là một ví dụ về mô hình này, vì nhiều tiện ích mở rộng bao gồm các hằng số và các chức năng như tiện ích mở rộng tokenizer. Người ta có thể nghĩ về phần mở rộng tokenizer dưới dạng gói: nó là một tập hợp hoàn chỉnh các dữ liệu, biến và chức năng có thể được sử dụng trong các chương trình khác. Một định dạng có cấu trúc hơn của mô hình này là tất nhiên các đối tượng hoặc các lớp. Một lớp chứa các biến và hàm (nhưng không có hằng số trong PHP). Một gói lớp duy nhất cùng nhau các chức năng và biến liên quan sẽ được sử dụng lại.

PhpDocumentor định nghĩa gói theo hai cách:

1. Các chức năng, hằng số và các biến toàn cầu được nhóm thành các tệp (bởi hệ thống tập tin), lần lượt được nhóm thành các gói bằng cách sử dụng thẻ @package trong một tài liệu cấp độ trang

2. Phương pháp và biến lớp được nhóm thành các lớp (theo pH), lần lượt được nhóm thành các gói trong một lớp học tập

1. /**

2. {

3.  * Pretend this is a file

4.  *

5.  * Page-level DocBlock is here because it is the first DocBlock

6.  * in the file, and is immediately followed by the second

7.  * DocBlock before any documentable element is declared

8.  * (function, define, class, global variable, include)

9.  * @package pagepackage@package pagepackage

10.  */

11. {

12.  * Here is the class DocBlock

13.  *

14.  * The class package is different from the page package!

15.  * @package classpackage@package classpackage

16.  */

17. class myclassmyclass

18. }

19. ?>

20. Để biết thêm thông tin về bao bì cấp độ trang so với mức độ lớp, hãy xem các yếu tố thủ tục

Có lẽ cách tốt nhất để tổ chức các gói là đặt tất cả các mã thủ tục vào các tệp riêng biệt từ các lớp. Pear khuyên bạn nên đặt mọi lớp vào một tệp riêng biệt. Đối với các lớp nhỏ, tiện ích, đây có thể không phải là giải pháp tốt nhất cho tất cả các trường hợp, nhưng tốt nhất là nên tách các gói thành các tệp khác nhau để thống nhất.

PhpDocum số tiên tiến: Hướng dẫn và tài liệu mở rộng

Các nhà phát triển PHPDocumentor đã nhận được một số yêu cầu cho phép liên kết với tài liệu bên ngoài và các phần của tài liệu đó. Nếu PhpDocumentor chỉ có thể tạo các tài liệu HTML, thì đây sẽ là một nhiệm vụ đơn giản, nhưng sự hiện diện của PDF và bây giờ là bộ chuyển đổi XML cũng như các khả năng trong tương lai làm phức tạp câu hỏi này rất nhiều. Giải pháp là gì?

Cung cấp cho PhpDocomeroRor khả năng phân tích các tài liệu bên ngoài theo định dạng chung và sau đó chuyển đổi nó thành định dạng thích hợp cho mỗi bộ chuyển đổi. Việc thực hiện giải pháp này trong phiên bản 1.2.0 rất linh hoạt. Sử dụng định dạng DOCBOOK XML tiêu chuẩn, tài liệu bên ngoài có thể được thiết kế và sau đó được định dạng lại cho bất kỳ đầu ra nào. Không còn là tài liệu bên ngoài gắn liền với một "cái nhìn". Đây là một danh sách ngắn về lợi ích của phương pháp này:

Lợi ích của việc sử dụng DocBook làm định dạng:

Docbook rất giống với HTML ở cấp độ cơ bản và rất dễ học.

• Mỗi mẫu có tệp Tùy chọn riêng.ini xác định cách các thẻ DocBook sẽ được dịch sang ngôn ngữ đầu ra - không cần phải học XSLT.

• Thêm vào hỗ trợ XSLT sẽ rất dễ dàng để cho phép tùy chỉnh trong tương lai

• Lợi ích của việc tích hợp các hướng dẫn/tài liệu bên ngoài vào PhpDocom số:

• Liên kết với tài liệu API từ tài liệu bên ngoài cũng có thể

• Bảng nội dung có thể tùy chỉnh, cả hai hướng dẫn và trong một hướng dẫn thông qua nội tuyến {@toc}

• Có thể tạo tài liệu cấp người dùng có quyền truy cập trực tiếp vào tài liệu cấp độ lập trình viên

• Tài liệu cấp độ người dùng thường bao gồm các hướng dẫn và thông tin về cách sử dụng gói và tránh cực kỳ chi tiết. Mặt khác, tài liệu cấp độ lập trình có tất cả các chi tiết mà một lập trình viên cần để mở rộng và sửa đổi một gói. PhpDocumentor đã hỗ trợ việc tạo ra tài liệu cấp trình lập trình kể từ khi thành lập. Với việc bổ sung các hướng dẫn, giờ đây nó có thể dễ dàng tạo ra tài liệu cấp người dùng.

Để có cái nhìn sâu sắc về cách sử dụng các hướng dẫn, hãy đọc hướng dẫn của PHPDocumentor

Có hai cách đóng gói để gọi phpDocomentor, phpDoc dòng lệnh hoặc giao diện web phpDoc.php/new_phpdoc.php.

Running phpDocumentor

Sử dụng giao diện web mới docbuilder

Giao diện web mới yêu cầu cài đặt PHP hoạt động với máy chủ web và phải có thể truy cập từ gốc tài liệu. DocBuilder là việc tạo ra Andrew Eddies và nó kết hợp một số định dạng bóng bẩy với chức năng của giao diện web cũ. Giao diện DocBuilder có thể được truy cập thông qua Index.html trong thư mục cài đặt của PhpDocomentor hoặc SubDirectory docBuilder.

Sử dụng giao diện web cũ phpdoc.php hoặc new_phpdoc.php

Để sử dụng giao diện web, có một số yếu tố phải được thiết lập trước khi bất cứ điều gì khác có thể xảy ra. Đầu tiên, bạn cần một máy chủ web hoạt động với PHP (phải nói). Hướng dẫn này sẽ không hỗ trợ với thiết lập đó. Tiếp theo, tệp phpdoc.php hoặc new_phpdoc.php cần được truy cập bởi máy chủ web. Trong Unix, đặt một liên kết tượng trưng bằng cách sử dụng LN -S vào giao diện mong muốn vào thư mục HTML công khai.

Bảo mật luôn là một vấn đề với Internet. Không đặt PHPDocomeror vào máy chủ web có sẵn đường dẫn công khai trên máy chủ được kết nối với Internet. Đảm bảo rằng PHPDocomentor sẽ không có khả năng ghi đè lên bất kỳ hệ thống hoặc tệp người dùng nào.

Lưu ý rằng vì máy chủ web chạy với tư cách là người dùng không ai trong Unix, các tệp được tạo sẽ được sở hữu bởi NOBODY. Cách duy nhất để thay đổi điều này là chạy phpDocomentor từ dòng lệnh hoặc thêm trình bao bọc chuser xung quanh httpd. Chúng tôi không khuyên bạn nên sử dụng trình bao bọc chuser hoặc chạy phpDocom số làm root. Việc sử dụng tệp cấu hình sẽ dễ dàng hơn nhiều và an toàn hơn nhiều (xem các tệp cấu hình do người dùng định nghĩa động của PHPDocumentor) từ dòng lệnh.We do not recommend using a chuser wrapper or running phpDocumentor as root. It is much easier and safer to use a config file (see phpDocumentor's dynamic User-defined config files) from the command line.

Sử dụng công cụ dòng lệnh

Chạy dòng lệnh trong Windows MS

Chạy PHPDocomentor từ dòng lệnh khá đơn giản, ngay cả trong Windows. Nên sử dụng giao diện web trong Windows, từ một root máy chủ không có thể truy cập công khai, vì không có vấn đề về quyền nào tồn tại trong Unix. Tuy nhiên, để sử dụng phpDocom số từ dòng lệnh là có thể. Đầu tiên, đặt vị trí của PHP vào đường dẫn hệ thống, sau đó nhập:

C:\>php-cli C:\path\to\phpdoc\phpdoc [commandline]

Một giải pháp thay thế là chỉnh sửa tệp PHPDoc.bat và đặt PHPDOC vào đường dẫn, sau đó bạn có thể chạy PHPDOC làm lệnh bình thường.

Chạy dòng lệnh trong Unix

Chạy công cụ dòng lệnh PHPDOC rất dễ dàng trong Unix:

.\phpdoc [commandline]

-c, - -config

Sử dụng tùy chọn này để tải tệp cấu hình (xem các tệp cấu hình do người dùng động của PhpDocumentor của PHPDocumentor)

"Mặc định phpDoc -c" sẽ tải tệp default.ini

-cp, - -converterparams

Tùy chọn này chỉ được sử dụng để chuyển các tham số động cho các bộ chuyển đổi mở rộng. Các tùy chọn được truyền nên được phân tách bằng dấu phẩy và được đặt trong biến toàn cầu $ _PhPDocumentor_Sinstall ['ConverterParams'], một mảng. Trách nhiệm của bộ chuyển đổi là truy cập biến này, mã được bao gồm trong PHPDocomentor không làm gì với nó.

-CT, - -Customtags

Sử dụng tùy chọn này để chỉ định các thẻ nên được đưa vào danh sách các thẻ hợp lệ cho lần chạy hiện tại của PHPDoc

"PHPDOC -CT MyTag, AnotherTag" sẽ nói với PhpDocumentor để phân tích DocBlock này:

1. /**

2.  * @mytag this is my tag@mytag this is my tag

3.  * @anothertag this is another tag@anothertag this is another tag

4.  */

mà không nêu bất kỳ lỗi nào và bao gồm các thẻ trong danh sách thẻ đã biết cho mẫu để xử lý. Lưu ý rằng trong phiên bản 1.2.0+, mảng không biết_tags được truyền cho các mẫu.

-dh, -ẩn

Sử dụng tùy chọn này để nói với PhpDocomentor cho các tệp và thư mục phân tích bắt đầu bằng một khoảng thời gian (.)

-DC, - -defaultc CategoryName

Điều này sẽ nói với PhpDocumentor để nhóm bất kỳ phần tử chưa được phân loại vào tên chính. Nếu không được chỉ định, danh mục chính là "mặc định." Danh mục phải được chỉ định bằng thẻ @C -Category.

1. /**

2.  * This package has no category and will be grouped into the default

3.  * category unless -dc categoryname is used

4.  * @package mypackage@package mypackage

5.  */

6. class nocategorynocategory

7. {

8. }

-Dn, - -defaultpackagename

Sử dụng tùy chọn này để nói với PHPDocomerTor gì tên của gói chính là gì. Điều này cũng sẽ nói với PhpDocumentor để nhóm bất kỳ yếu tố chưa đóng gói nào vào tên gói chính. Nếu không được chỉ định, gói chính là "mặc định"

1. /**

2.  * This class has no package and will be grouped into the default

3.  * package unless -dn packagename is used

4.  */

5. class nopackagenopackage

6. {

7. }

-Dn, - -defaultpackagename

Sử dụng tùy chọn này để nói với PHPDocomerTor gì tên của gói chính là gì. Điều này cũng sẽ nói với PhpDocumentor để nhóm bất kỳ yếu tố chưa đóng gói nào vào tên gói chính. Nếu không được chỉ định, gói chính là "mặc định"

-D, - -Directory

Tùy chọn này hoặc tùy chọn -F phải có mặt, trên dòng lệnh hoặc trong tệp cấu hình.

Không giống như -f, -d không chấp nhận ký tự đại diện. Sử dụng -D để chỉ định các đường dẫn đầy đủ hoặc đường dẫn tương đối đến thư mục hiện tại mà PhpDocomentor nên tìm kiếm đệ quy các tệp có thể ghi lại. PhpDocumentor sẽ tìm kiếm thông qua tất cả các thư mục con của bất kỳ thư mục nào trong danh sách dòng lệnh cho các hướng dẫn/ và bất kỳ tệp nào có các tiện ích mở rộng .php hợp lệ như được định nghĩa trong phpDocumentor.ini. Ví dụ:

"PHPDOC -D tương đối/đường dẫn/to/dir1,/fullpath/to/đây, .."

-Ed, --Examplesdir

Tùy chọn -ED được sử dụng để chỉ định đường dẫn đầy đủ đến thư mục mà các tệp ví dụ được đặt ở. Cài đặt dòng lệnh này ảnh hưởng đến đầu ra của thẻ @example.

"PHPDOC -ED/fullPath/to/example"

-f, - -filename

• Tùy chọn này hoặc tùy chọn -D phải có mặt, trên dòng lệnh hoặc trong tệp cấu hình.

• Tùy chọn này được sử dụng để chỉ định các tệp hoặc biểu thức riêng lẻ với Wildcards * và?. Sử dụng * để phù hợp với bất kỳ chuỗi nào, và? Để phù hợp với bất kỳ ký tự đơn.

• PHPDOC -f M* .P* sẽ khớp với myfile.php, Mary_who.isthat.phtml, v.v.

PhpDoc -f/path/m* sẽ khớp /path/my/files/erm.php, /path/mommy.php /path/mucho/grande/what.doc, v.v.

Tệp PHPDOC -F?

• -i, --ignore

• Sử dụng tùy chọn -i để loại trừ các tệp và thư mục khỏi phân tích cú pháp. Tùy chọn -i nhận ra * và? Các ký tự đại diện, như -f không. Ngoài ra, có thể bỏ qua một thư mục con của bất kỳ thư mục nào bằng cách sử dụng "dirname/".

• Các thử nghiệm phpDoc -i/sẽ bỏ qua/đường dẫn/đến/đây/thử nghiệm/* và/path/tests/*

• phpDoc -i *.inc sẽ bỏ qua tất cả các tệp .inc

PhpDoc -i* path/to/* sẽ bỏ qua/path/path/to/my/* cũng như/path/to/*

• PhpDoc -i* test* sẽ bỏ qua/path/tests/* và//

• Vì v1.3.2, giá trị hoặc mẫu bạn cung cấp sẽ nhạy cảm với trường hợp (dù sao cũng cho phép HĐH) và sẽ được áp dụng so với thư mục cấp cao nhất trong đối số -D.

PhpDoc -i cvs/will bỏ qua/path/to/cvs/* nhưng sẽ không bỏ qua/đường dẫn/đến/cvs

PHPDOC -D/home/myhome/cvs/myProject -i cvs/will bỏ qua/home/myhome/cvs/myproject/files/cvs/* nhưng sẽ không bỏ qua/home/myhome/cvs/*

-is, --Ignoresymlinks

Sử dụng tùy chọn -s để bỏ qua rõ ràng bất kỳ liên kết nào, cho dù chúng là liên kết đến các thư mục hoặc liên kết đến các tệp.

Điều này chỉ hoạt động trên môi trường Unix/Linux, vì Windows không có liên kết symlink.

-it,--gags

--gigore-tags sẽ không bỏ qua các thẻ cốt lõi @global, @access, @package, @ignore, @Name, @param, @return, @staticvar hoặc @var.

Tùy chọn --gigore-Tags yêu cầu một tên thẻ đầy đủ như --gigore-tag @Todo. -Tago-Tag Tags sẽ không hoạt động.

-O, --Output

Sử dụng tùy chọn yêu cầu này để nói với PhpDocomentor mà bộ chuyển đổi và mẫu sử dụng. Trong bản phát hành này, có một số lựa chọn:

• HTML: khung:* - Đầu ra là HTML với khung.

  • HTML: khung: Mặc định - Mẫu giống như Javadoc, rất đơn giản, định dạng tối thiểu

  • HTML: khung: Earthli - Mẫu đẹp được viết bởi Marco von Ballmoos

  • HTML: khung: L0L33T - Mẫu sành điệu

  • Html: khung: phpdoc.de - tương tự như đầu ra phpDoc của phpDoc.de

  • HTML: khung: PhphtMllib - Mẫu

  • Tất cả các mẫu được liệt kê ở trên cũng có sẵn với các chỉ mục có thể mở rộng JavaScripted, như HTML: FRAME: DOM/Tên nơi tên là mặc định, L0L33T, PHPDOC.DE, ETCetera

  • HTML: khung: Phpedit - Dựa trên đầu ra từ Trình tạo trợ giúp Phpedit

• HTML: Smarty:* - Đầu ra là HTML không có khung.

  • HTML: Smarty: Mặc định - Thiết kế mẫu đậm bằng cách sử dụng CSS để kiểm soát bố cục

  • HTML: Smarty: Bàn tay - Bố cục dựa trên PHP, nhưng tinh tế hơn, với hình ảnh logo

  • HTML: Smarty: PHP - Bố cục giống hệt với trang web PHP

• CHM: Mặc định:* - Đầu ra là CHM, được biên dịch định dạng tệp trợ giúp (trợ giúp Windows).

  • CHM: Mặc định: Mặc định - Tệp trợ giúp Windows, dựa trên HTML: khung: L0L33T

• PDF: Mặc định:* - Đầu ra là định dạng PDF, Adobe Acrobat

  • PDF: Mặc định: Mặc định - Định dạng PDF tiêu chuẩn, đơn giản

• XML: DocBook:* - Đầu ra là XML, ở định dạng DocBook

  • XML: DocBook/Peardoc2: Mặc định - Tài liệu sẵn sàng biên dịch vào Peardoc cho tài liệu trực tuyến Pear.php.net, Bản sửa đổi thứ 2

Trong 1.2.0+, có thể tạo đầu ra cho một số bộ chuyển đổi và/hoặc mẫu cùng một lúc. Chỉ cần chỉ định một danh sách đầu ra được phân phối bằng dấu phẩy: Bộ chuyển đổi: Mẫu như:

PHPDOC -O HTML: khung: Mặc định, HTML: Smarty: PHP, HTML: khung: Phpedit, PDF: Mặc định: Mặc định -t ./docs -d.

-PP, --parseprivate

Theo mặc định, PHPDocomentor không tạo tài liệu cho bất kỳ yếu tố nào được đánh dấu @Access Private. Điều này cho phép tạo các tài liệu API của người dùng cuối lọc ra thông tin cấp thấp sẽ không hữu ích cho hầu hết các nhà phát triển sử dụng mã của bạn. Để tạo tài liệu đầy đủ của tất cả các yếu tố, hãy sử dụng tùy chọn dòng lệnh này để bật phân tích các yếu tố được đánh dấu riêng tư với @Access Private.

-PO, - -gói hàng hóa

Sử dụng tùy chọn này để loại bỏ tất cả các phần tử được nhóm bởi các thẻ @package trong danh sách phân loại bằng dấu phẩy từ đầu ra. Tùy chọn này hữu ích cho các dự án không được tổ chức thành các tệp riêng biệt cho mỗi gói. Tốc độ phân tích cú pháp không bị ảnh hưởng bởi tùy chọn này, sử dụng -i, --ignore bất cứ khi nào có thể thay vì - -gói hàng hóa.

PHPDOC -O HTML: khung: DEFAULT -T ./DOCS -D. -Po MyPackage, ThatOtherPackage sẽ chỉ hiển thị tài liệu cho các phần tử được đánh dấu bằng "@Package myPackage" hoặc "@package thatertherpackage"

-P, - -Pear

Sử dụng tùy chọn này để phân tích một kho lưu trữ kiểu lê. PhpDocumentor sẽ làm một số điều "thông minh" để làm cho cuộc sống dễ dàng hơn:

• Bộ hủy diệt kiểu lê được phân tích cú pháp tự động

• Nếu không có thẻ @package có mặt trong tệp hoặc lớp docblock, nó sẽ đoán gói dựa trên thư mục con

• Nếu một biến hoặc tên phương thức bắt đầu bằng "_", nó sẽ được giả định là @Access Riêng tư, trừ khi có thẻ @Access. Các hàm tạo cũng được coi là @Access Private trong phiên bản hiện tại.

Cảnh báo sẽ được nêu ra cho mọi trường hợp ở trên, vì @Package phải luôn luôn rõ ràng, như @Access Riêng tư. Chúng tôi không thích giả định rằng PhpDocomentor hiểu rõ hơn bạn phải làm gì với mã của bạn, và do đó sẽ luôn yêu cầu sử dụng rõ ràng hoặc đưa ra cảnh báo nếu PHPDocomophyor đưa ra bất kỳ giả định nào.

-Q, --quiet

Tùy chọn này bảo PhpDocum số để triệt tiêu đầu ra của thông tin phân tích cú pháp/chuyển đổi thành bảng điều khiển. Sử dụng điều này cho các công việc cron hoặc các tình huống khác mà sự can thiệp của con người sẽ không cần thiết.

-ric, --ReadMeInstallChangelog

Danh sách các tệp được phân tách bằng dấu phẩy này chỉ định các tệp nên được phân tích cú pháp và được đưa vào tài liệu. PhpDocumentor sẽ tự động lấy các tệp được liệt kê ở đây khi và chỉ khi chúng được đặt trong thư mục cấp cao nhất được phân tích cú pháp. Nói cách khác, nếu bạn phân tích các tệp này:

• /path/to/files/file1.php
  
• /path/to/files/file2.php
  
• /path/to/files/README
  
• /path/to/files/subdir/file2.php
  
• /path/to/files/subdir/README
  

Tệp readme duy nhất sẽ được lấy là/path/to/file/readme, và không/path/to/files/subdir/reamde, bởi vì thư mục gần nhất với thư mục gốc chứa tệp được phân tích cú pháp là/path/path đến/tập tin.

Danh sách các tệp mặc định được đặt trong phpDocomentor.ini, được tìm thấy trong thư mục cài đặt gốc của phpDocomentor.

-S, - -SourceCode

Tùy chọn này bảo PhpDocomentor tạo mã nguồn tham chiếu chéo được tô sáng cho mỗi tệp được phân tích cú pháp. Mã làm nổi bật có phần không ổn định, vì vậy hãy sử dụng tùy chọn này có nguy cơ của riêng bạn.

-t, -mục tiêu

Sử dụng điều này để nói với PhpDocumentor nơi đặt tài liệu được tạo. Các giá trị pháp lý là các đường dẫn mà PhpDocom số sẽ có quyền truy cập ghi và tư nhân tạo thư mục.

-TB, - -TemplateBase

-TB chấp nhận một tên đường dẫn duy nhất là tham số của nó. Giá trị mặc định của -TB nếu không xác định là /phpDocom số. Điều này làm tăng một điểm rất quan trọng để hiểu. Dòng lệnh -TB được thiết kế để nói với PhpDocomentor tìm kiếm tất cả các mẫu cho tất cả các bộ chuyển đổi trong các thư mục con của đường dẫn được chỉ định. Theo mặc định, các mẫu được đặt trong một cấu trúc thư mục đặc biệt.all templates for all converters in subdirectories of the path specified. By default, templates are located in a special subdirectory structure.

Đối với đầu ra giả thuyết: ConverterName: TemplatEname -o, đối số --Output, cấu trúc thư mục là Trình chuyển đổi/OutputFormat/ConvertName/Mẫu/Templatename/. Tệp lớp cho ConvertName phải nằm trong Trực tiếp/Mẫu ConvertName, ngay bên cạnh thư mục Templatename/IES của bạn. Ngoài ra, Smarty dự kiến ​​sẽ tìm thấy hai thư mục con, mẫu/ (chứa các tệp mẫu Smarty) và Mẫu_C/ (sẽ chứa các tệp mẫu được biên dịch).

"PHPDOC -TB ~/PHPDOCTEMPLATE -O /mặc định/Mẫu_C tồn tại.

-Ti, -tựa đề

Đặt tiêu đề toàn cầu của tài liệu được tạo

-Ue, --UndocalesEdelements

Tùy chọn này nói với PhpDocumentor liệu có nên triệt tiêu các cảnh báo về một số đối tượng nhất định (lớp, phương thức) không được ghi lại thông qua nhận xét docblock. Sử dụng điều này để giúp xác định các đối tượng mà bạn vẫn cần viết tài liệu cho.

Các tệp cấu hình do người dùng động của PhpDocumentor của PhpDocumentor

Tùy chọn dòng lệnh mới -c, - -config báo hiệu một kỷ nguyên mới dễ dàng trong việc sử dụng PhpDocom số. Những gì được sử dụng để yêu cầu:

phpdoc -t /path/to/output -d path/to/directory1,/another/path,/third/path\
-f /path/to/anotherfile.php -i *test.php,tests/ -pp on -ti My Title -o HTML:frames:phpedit
    

Bây giờ có thể được thực hiện trong một cú đánh duy nhất!

phpdoc -c myconfig
    

Điều làm cho tất cả điều này có thể là việc sử dụng các tệp cấu hình chứa tất cả các thông tin dòng lệnh. Có hai tệp cấu hình được bao gồm trong phân phối của PhpDocomentor và cả hai đều nằm trong người dùng/ thư mục con. Để sử dụng tệp cấu hình "myconfig.ini", chỉ cần đặt nó vào thư mục người dùng và dòng lệnh "phpDoc -c myconfig" sẽ cho phpDocumentor đọc tất cả các cài đặt dòng lệnh từ tệp cấu hình đó. Các tệp cấu hình cũng có thể được đặt trong một thư mục khác, chỉ cần chỉ định đường dẫn đầy đủ đến tệp cấu hình:

phpdoc -c /full/path/to/myconfig.ini
    

Cách tốt nhất để đảm bảo tệp cấu hình của bạn phù hợp với định dạng mà phpDocumentor dự kiến ​​là sao chép tệp cấu hình mặc định và sửa đổi nó để phù hợp với nhu cầu của bạn. Các dòng bắt đầu bằng một đại hội (;) bị bỏ qua và có thể được sử dụng cho các bình luận.

PhpDocumentor.ini - Tùy chọn cấu hình toàn cầu

Tệp phpDocomentor.ini chứa một số tùy chọn hữu ích, hầu hết trong số đó sẽ không bao giờ cần phải thay đổi. Tuy nhiên, một số là hữu ích. Phần [_phpDocomentor_options] chứa một số cài đặt cấu hình có thể được thay đổi để tăng cường tài liệu đầu ra. Đối với vị trí chương trình, đường dẫn tương đối được chỉ định là Program_root/RelativePath/to/file. Tiền tố "Program_root" có thể được thay đổi thành bất kỳ văn bản nào, bao gồm không có gì cả hoặc "bao gồm", v.v. Bất kỳ đối số dòng lệnh nào! Phần [_PhpDocumentor_phpFile_exts] cho PhpDocumentor cho các phần mở rộng tệp là các tệp PHP, thêm bất kỳ tiện ích mở rộng không chuẩn nào, chẳng hạn như "Lớp" vào phần này.