• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    公众号

victorjonsson/PHP-Markdown-Documentation-Generator: Write documentation once, an ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

victorjonsson/PHP-Markdown-Documentation-Generator

开源软件地址(OpenSource Url):

https://github.com/victorjonsson/PHP-Markdown-Documentation-Generator

开源编程语言(OpenSource Language):

PHP 100.0%

开源软件介绍(OpenSource Introduction):

PHP-Markdown-Documentation-Generator

Documentation is just as important as the code it's refering to. With this command line tool you will be able to write your documentation once, and only once!

This project will write a single-page markdown-formatted API document based on the DocBlock comments in your source code.

Travis

Example

Let's say you have your PHP classes in a directory named "src". Each class has its own file that is named after the class.

- src/
  - MyObject.php
  - OtherObject.php

Write your code documentation following the standard set by phpdoc.

namespace Acme;

/**
 * This is a description of this class
 */
class MyObject {
   
   /**
    * This is a function description
    * @param string $str
    * @param array $arr
    * @return Acme\OtherObject
    */
   function someFunc($str, $arr=array()) {
   
   }
}

Then, running $ phpdoc-md generate src > api.md will write your API documentation to the file api.md.

Here you can see a rendered example

Only public and protected functions will be a part of the documentation, but you can also add @ignore to any function or class to exclude it from the docs. Phpdoc-md will try to guess the return type of functions that don't explicitly declare one. The program uses reflection to get as much information as possible out of the code so that functions that are missing DocBlock comments will still be included in the generated documentation.

Requirements

  • PHP version >= 5.3.2
  • Reflection must be enabled in php.ini
  • Each class must be defined in its own file with the file name being the same as the class name
  • The project should use Composer

Installation / Usage

This command line tool can be installed using composer.

From the local working directory of the project that you would like to document, run:

$ composer require --dev victorjonsson/markdowndocs

This will add victorjonsson/markdowndocs to the require-dev section of your project's composer.json file. The phpdoc-md executable will automatically be copied to your project's vendor/bin directory.

Generating docs

The generate command generates your project's API documentation file. The command line tool needs to know whether you want to generate docs for a certain class, or if it should process every class in a specified directory search path.

# Generate docs for a certain class
$ ./vendor/bin/phpdoc-md generate Acme\\NS\\MyClass 

# Generate docs for several classes (comma separated)
$ ./vendor/bin/phpdoc-md generate Acme\\NS\\MyClass,Acme\\OtherNS\\OtherClass 

# Generate docs for all classes in a source directory
$ ./vendor/bin/phpdoc-md generate includes/src

# Generate docs for all classes in a source directory and send output to the file api.md
$ ./vendor/bin/phpdoc-md generate includes/src > api.md
  • Note that any class to be documented must be loadable using the autoloader provided by composer. *
Bootstrapping

If you are not using the composer autoloader, or if there is something else that needs to be done before your classes can be instantiated, then you may request phpdoc-md to load a php bootstrap file prior to generating the docs

$ ./vendor/bin/phpdoc-md generate --bootstrap=includes/init.php includes/src > api.md

Excluding directories

You can tell the command line tool to ignore certain directories in your class path by using the --ignore option.

$ ./phpdoc-md generate --ignore=test,examples includes/src > api.md




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
notlmn/copy-as-markdown: 发布时间:2022-08-18
下一篇:
huaxz1986/markdown_documentation_chinese: A Chinese markdown documentation to do ...发布时间:2022-08-18
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap