Сборка документации с PHP-кода

Question

Я слышал, что руководство .NET было создано из кода, а наиболее важные части вручную были улучшены позже.

У Google пока ничего не появилось. Большинство вещей, которые я нашел, связаны с кодированием и документированием лучших практик. Но не документирование, которое может помочь позже построить руководство, и особенно не решение, которое это сделает. Даже если не ограничивать поиск PHP.

Кто-нибудь знает, какое решение желательно использовать на PHP, которое может создавать похожие документы из кода PHP?

Answer 1

Поскольку это казалось забавным, я построил это для практики и образования.

Я обнаружил, что это на самом деле более удобно, чем все остальное, поскольку это позволит мне создавать мои документы, как я их хочу.

Я также построил для него генератор 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 2

я считаю, 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 3

Либо PhpDocumentor или ApiGen - это хорошо. Тем не менее, PHP.net может использовать специальную команду, созданную только для них (а также получение дополнительной информации из базы данных, например, списков изменений, и, безусловно, примеров пользователей и голосов).

Очень важно помнить, что нет стандартного документа, например, и каждое решение может реализовать свои собственные, в зависимости от их потребностей или видения. К счастью, все они пытаются сделать то же, что делает Джавадок.

Я немного искал Google, и я не вижу тега @changelog для Javadoc, поэтому, возможно, единственный способ - сделать вашу собственную структуру в каждом докблоке, а затем проанализировать ее с помощью некоторых стилей после создания документации.