Question

我听说.NET手册是根据代码构建的，最重要的部分后来手动改进了。

到目前为止，谷歌还没有发现任何事情。我发现的大多数东西都与编码和记录最佳实践有关。但是没有记录可以帮助以后构建手册，特别是不能解决问题。即使没有将搜索限制为PHP。

有没有人知道最好用PHP构建的解决方案，可以用PHP代码构建类似的文档？

Answer 1

我相信phpdoc是您要找的词：

http://en.wikipedia.org/wiki/PHPDoc

我个人使用http://www.phpdoc.org/实施

示例：在定义函数之前放置它

 /**
  * This is the short description for a DocBlock.
  *
  * This is the long description for a DocBlock. This text may contain
  * multiple lines and even some _markdown_.
  *
  *
  * @author  Mike van Riel
  *
  * @since 1.0
  *
  * @param int    $example  This is an example function/method parameter description.
  * @param string $example2 This is a second example.
  * @return int
  */
  function docBlock($example, $example2){
      return $example*intval($example2);
  }

Answer 2

PhpDocumentor或ApiGen都不错。但是，PHP.net可能正在使用一个特殊的命令，只为它们制作（或者从数据库获取额外的信息，比如更改日志，绝对是用户示例和投票）。

非常重要的是，请记住，没有文档标准，并且每个解决方案都可以根据自己的需求或愿景实施自己的标准。幸运的是，他们都试图像Javadoc那样做。

我已经用Google搜索了一点，我没有看到Javadoc的@changelog标记，所以也许唯一的方法是在每个docblock中执行自己的结构，然后在生成文档后用一些样式解析它。 / p>

Answer 3

因为看起来很有趣，我为实践和教育建立了这个。

我发现它实际上比其他所有内容都更方便，因为它可以让我按照我的意愿构建我的文档。

我还为它构建了一个HTML生成器，如果有人想要它我会发布它。

请不要咄咄逼人。

<?php

/**moDO(Classes)(Modo)(Modo_Parse)

  @(Description)
    Parses Many One standard code comments and produces an array that can be used to build web manuals.


  @(Syntax){quote}
    object `Modo_Parse` ( string ~$contents~ )


  @(Parameters)
  @(Parameters)($contents)(1){info}
    Contents of the code files that contain code comments to be parsed.

  @(Parameters)($contents)(2){note warn}
    Please note very long contents can cause performance issues. 
    It is recommended that you run the parser file by file.


  @(Return)
    Returns an object that contains a variable `parsed` that contains the resulting array.


  @(Examples)
  @(Examples)(1){info}
    `Example 1:` Basic usage example.

  @(Examples)(2){code php}
  $contents = file_get_contents("Modo_Parse.php");
  $parser = new Modo_Parse($contents);
  print_r($parser->parsed);


  @(Changelog){list}
   (1.0) ~Initial release.~

*/

  /**
  * Parses Many One standard code comments and produces an array that can be used to build manuals.
  * @syntax new Modo_Parse($contents);
  * @contents string containing codes with comments to be parsed
  */
  class Modo_Parse {
    /**
    * Takes the parameter and calls the parser function.
    */
    function __construct($contents) {
      // standardise line breaks
      $contents = str_replace(Array("\r\n", "\n\r", "\n"), Array("\n", "\n", "\r\n"), $contents);

      $this->parsed = $this->parser((string)$contents);
    }

    /**
    * The parser function that does all the work.
    */
    private function parser($contents) {
      $return = Array();

      // Identify docs
      preg_match_all('/(\/\*\*moDO(\([a-z \$_-]+\))+\s+)(.*?)(\s*\r\n*\*\/\r\n)/is', $contents, $docs);

      foreach($docs[0] AS $doc) {
        $records = Array();

        // Extract and prepare log header
        $header = explode("\n", trim($doc));
        $header = trim(rtrim(str_replace("/**moDO", "", $header[0])));
        $header = explode("|", str_replace(Array(")(", "(", ")"), Array("|", "", ""), $header));

        // Identify log records
        preg_match_all('/((@\([a-z0-9 \$_-]+\)+(\{[a-z0-9 _-]+\})?))(.*?)+(?=@\([a-z0-9 \$_-]+\)|\*\/)/is', $doc, $log_records);

        foreach($log_records[0] AS $record) {
          // Separate header and text
          preg_match("/(@(\([a-z0-9 \$_-]+\))+(\{[a-z0-9 _-]+\})?)(.*)/is", trim($record), $separated);

          // Extract and prepare record header and style
          $record_head = str_replace(Array("@", ")(", "(", ")", "{", "}"), Array("", "|", "", "", "~", ""), $separated[1]);
          $record_head = explode("~", $record_head);
          if(count($record_head) == 1) {
            $record_head[] = "";
          }
          $record_head = Array(explode("|", $record_head[0]), $record_head[1]);

          // Prepare record text
          if(!strstr($record_head[1], "code")) {
            $separated[4] = trim(implode("\n", array_map('trim', explode("\n", $separated[4]))));
          }
          $separated[4] = preg_replace("/^(\r\n)(.*)/", "$2", rtrim($separated[4]));

          $record_text = preg_replace(Array("/</", "/>/", "/`(.*?)`/", "/~(.*?)~/"), Array("&lt;", "&gt;", "<b>$1</b>", "<i>$1</i>"), $separated[4]);

          // Find and set Links
          preg_match_all("/(\&gt\;)([a-z-.:\/]+)(( )([a-z .,;:-_]+))?(\&lt\;)/i", $record_text, $anchors, PREG_SET_ORDER);
          if(!empty($anchors)) {
            foreach($anchors AS $anchor) {
              if(empty($anchor[5])) {
                $anchor[5] = $anchor[2];
              }
              $record_text = str_replace($anchor[0], '<a href="' . $anchor[2] . '" target="_blank">' . $anchor[5] . '</a>', $record_text);
            }
          }

          // Merge the data together
          $records = $this->array_merge_recursive_distinct($records, $this->array_chain($record_head[0], Array("style" => $record_head[1], "text" => $record_text)));
        }

        $return[] = Array("log" => $header, "data" => $records);
      }

      return $return;
    }

    /**
    * Turns a list into a chain of keys with the value in the last key.
    */
    private function array_chain(Array $keys, $value) {
      $first = array_shift($keys);

      if (count($keys) === 0) {
        $return = Array($first => $value);
      }
      else {
        $return = Array($first => $this->array_chain($keys, $value));
      }

      return $return;
    }

    /**
    * Distinct recursive array merge.
    */
    private function array_merge_recursive_distinct(Array &$array1, Array &$array2) {
      $merged = $array1;

      foreach($array2 as $key => &$value) {
        if(is_array($value) && isset($merged[$key]) && is_array($merged[$key])) {
          $merged[$key] = $this->array_merge_recursive_distinct($merged[$key], $value);
        }
        else {
          $merged[$key] = $value;
        }
      }

      return $merged;
    }
  }

Answer 4

与transilvlad发布的内容类似，我写了PHPFUI/InstaDoc以动态呈现文档。将大约5行代码添加到您的项目中，然后您将拥有完整和最新的文档，这些文档反映了您上次将其写入磁盘时的代码。

它也完全响应，因此可以在手机或平板电脑上很好地运行。或者，即使您尝试将编辑器，调试器，网页和文档塞入同一监视器中。它甚至显示PHP源代码（当然以您喜欢的样式突出显示）和文件的git历史记录。我发现在我的PHP工作中，将所有这些信息实时更新是非常有用的。

检出库。还很年轻，但是开源并且总是征求建议。

从PHP代码构建文档

4 个答案: