我听说.NET 手册是用代码构建的，最重要的部分后来手动改进了。
到目前为止，谷歌搜索还没有出现任何东西。我发现的大多数东西都与编码和记录最佳实践有关。但是没有记录可以帮助以后建立手册，尤其是不能做到这一点的解决方案。即使不将搜索限制为 PHP。
有谁知道最好用 PHP 构建的解决方案，它可以从 PHP 代码构建类似的文档？
问问题
224 次
4 回答
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);
}
于 2013-05-27T11:09:21.767 回答
0
PhpDocumentor或ApiGen都可以。然而，PHP.net 可能正在使用一个专门为他们制作的特殊命令（或者还从数据库中获取额外信息，如变更日志，当然还有用户示例和投票）。
非常重要的是，请记住，没有文档标准，例如，每个解决方案都可以实现自己的，具体取决于他们的需求或愿景。幸运的是，它们都试图做与 Javadoc 相同的事情。
我用谷歌搜索了一下，我没有看到 Javadoc 的 @changelog 标记，所以也许唯一的方法是在每个 docblock 中做你自己的结构，然后在生成文档后用一些样式解析它。
于 2013-05-28T10:32:39.857 回答
0
因为它看起来很有趣，所以我为实践和教育构建了这个。
我发现它实际上比其他任何东西都更方便，因为它可以让我根据需要构建我的文档。
我还为它构建了一个 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("<", ">", "<b>$1</b>", "<i>$1</i>"), $separated[4]);
// Find and set Links
preg_match_all("/(\>\;)([a-z-.:\/]+)(( )([a-z .,;:-_]+))?(\<\;)/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;
}
}
于 2013-06-24T18:09:25.300 回答
0
与 transilvlad 发布的内容类似，我编写了PHPFUI/InstaDoc来动态呈现文档。将大约 5 行代码添加到您的项目中，然后您将获得完整且最新的文档，这些文档反映了您上次将代码写入磁盘时的代码。
它也完全响应，因此它可以在您的手机或平板电脑上运行。或者即使您试图将您的编辑器、调试器、网页和文档塞到同一个监视器上。它甚至显示 PHP 源代码（当然以您喜欢的风格突出显示）和文件的 git 历史记录。我发现在我的 PHP 工作中让所有这些信息实时更新非常有用。
去图书馆看看。仍然有点年轻，但开源并且总是开放的建议。
于 2020-01-20T02:26:02.503 回答