Skip to content

Commit 221973f

Browse files
mpenickmpenick
committed
PHP-184 - Remove {@inheritdoc} from method parameters
* Moved common doc generator functionality into a common file. * Fixed unnecessary use of '{@inheritdoc}' in cases that wouldn't be caught by the `doc_generate_yaml.php` updates. * When generating the PHP API comments will be inherited from the parent if the subclass's comment is empty. * Fixed invalid `Dse\Table` comment * Fixed wrapping @return comments
1 parent aa7eb39 commit 221973f

33 files changed

+818
-723
lines changed

‎doxygen.rb

+4
Original file line numberDiff line numberDiff line change
@@ -25,4 +25,8 @@
2525
text.gsub!(/(\/\*\*[\s\S]*?@return\s+([^\s]*)[\s\S]*?\*\/[\s\S]*?)((public|protected|private)(\s+static)?)?\s+function\s+([\S]*?)\s*?\(/, '\1 \3 \2 function \6(')
2626
text.gsub!(/\@return/, '@retval')
2727

28+
text.gsub!(/function_/, 'function')
29+
text.gsub!(/Function_/, 'Function')
30+
text.gsub!(/Float_/, 'Float')
31+
2832
puts text

‎ext/doc/generate_doc.php

+110-98
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
<?php
22

3+
require_once(dirname(__FILE__) . DIRECTORY_SEPARATOR . "generate_doc_common.php");
4+
35
define("LICENSE_COMMENT", "/**
46
* Copyright 2017 DataStax, Inc.
57
*
@@ -27,12 +29,10 @@
2729
die("Usage: {$argv[0]} <directory>" . PHP_EOL);
2830
}
2931

30-
3132
define("BASEDIR", $argv[1]);
3233
define("SRCDIR", BASEDIR . "/src");
3334
define("DOCDIR", BASEDIR . "/doc");
3435

35-
define("INPUT_NAMESPACE", "Cassandra");
3636
define("OUTPUT_NAMESPACE", "Cassandra");
3737
define("INDENT", " ");
3838

@@ -63,21 +63,6 @@ function isAlreadyImplementedByBase($current, $implemented) {
6363
return false;
6464
}
6565

66-
function doesParentHaveMethod($class, $method) {
67-
$parent = $class->getParentClass();
68-
if ($parent) {
69-
if ($parent->hasMethod($method->getName())) {
70-
return true;
71-
}
72-
return doesParentHaveMethod($parent, $method);
73-
}
74-
return false;
75-
}
76-
77-
function logWarning($message) {
78-
fwrite(STDERR, "Warning: $message" . PHP_EOL);
79-
}
80-
8166
function replaceKeyword($string) {
8267
if ($string == "Function") {
8368
return "Function_";
@@ -112,6 +97,35 @@ function writeCommentDoc($file, $comment, $indent = 0) {
11297
writeCommentLines($file, $lines, $indent);
11398
}
11499

100+
function writeParamReturnCommentDoc($file, $typeAndName, $comment) {
101+
$lines = explode(PHP_EOL, $comment);
102+
if (strlen(end($lines)) == 0) {
103+
array_pop($lines);
104+
}
105+
106+
$first = true;
107+
if ($lines) {
108+
foreach($lines as $line) {
109+
if ($first) {
110+
$commentLine = "$typeAndName $line";
111+
$commentLine = rtrim($commentLine) . PHP_EOL;
112+
fwrite($file, INDENT . DOC_COMMENT_LINE . $commentLine);
113+
} else {
114+
$commentLine = str_pad("", strlen($typeAndName) + 1, " ") . $line;
115+
$commentLine = rtrim($commentLine) . PHP_EOL;
116+
$docCommentLine = DOC_COMMENT_LINE;
117+
if ($commentLine == PHP_EOL) {
118+
$docCommentLine = rtrim($docCommentLine);
119+
}
120+
fwrite($file, INDENT . $docCommentLine . $commentLine);
121+
}
122+
$first = false;
123+
}
124+
} else {
125+
fwrite($file, INDENT . DOC_COMMENT_LINE . $typeAndName . PHP_EOL);
126+
}
127+
}
128+
115129
function writeParameterDoc($doc, $file, $class, $method, $parameter) {
116130
$className = $class->getName();
117131
$methodName = $method->getShortName();
@@ -137,34 +151,7 @@ function writeParameterDoc($doc, $file, $class, $method, $parameter) {
137151

138152
$parameterType = $parameterType ? $parameterType : "mixed";
139153
$parameterType = $type ? $type : $parameterType; # Overrides builtin if provided
140-
$parameterTypeAndName = "@param $parameterType \$$parameterName";
141-
142-
$lines = explode(PHP_EOL, $comment);
143-
if (strlen(end($lines)) == 0) {
144-
array_pop($lines);
145-
}
146-
147-
$first = true;
148-
if ($lines) {
149-
foreach($lines as $line) {
150-
if ($first) {
151-
$commentLine = "$parameterTypeAndName $line";
152-
$commentLine = rtrim($commentLine) . PHP_EOL;
153-
fwrite($file, INDENT . DOC_COMMENT_LINE . $commentLine);
154-
} else {
155-
$commentLine = str_pad("", strlen($parameterTypeAndName) + 1, " ") . $line;
156-
$commentLine = rtrim($commentLine) . PHP_EOL;
157-
$doc_comment_line = DOC_COMMENT_LINE;
158-
if ($commentLine == PHP_EOL) {
159-
$doc_comment_line = rtrim($doc_comment_line);
160-
}
161-
fwrite($file, INDENT . $doc_comment_line . $commentLine);
162-
}
163-
$first = false;
164-
}
165-
} else {
166-
fwrite($file, INDENT . DOC_COMMENT_LINE . $parameterTypeAndName . PHP_EOL);
167-
}
154+
writeParamReturnCommentDoc($file, "@param $parameterType \$$parameterName", $comment);
168155
} else {
169156
$parameterType = $parameterType ? $parameterType : "mixed";
170157
fwrite($file, INDENT . DOC_COMMENT_LINE . "@param $parameterType \$$parameterName" . PHP_EOL);
@@ -190,9 +177,7 @@ function writeReturnDoc($doc, $file, $class, $method) {
190177
}
191178

192179
$type = $type ? $type : "mixed";
193-
$commentLine = "@return $type $comment";
194-
$commentLine = rtrim($commentLine) . PHP_EOL;
195-
fwrite($file, INDENT . DOC_COMMENT_LINE . $commentLine);
180+
writeParamReturnCommentDoc($file, "@return $type", $comment);
196181
} else {
197182
fwrite($file, INDENT . DOC_COMMENT_LINE . "@return mixed" . PHP_EOL);
198183
logWarning("Missing 'return' documentation for method '$className::$methodName()'");
@@ -462,74 +447,101 @@ function writeClass($doc, $file, $class) {
462447
fwrite($file, "}" . PHP_EOL);
463448
}
464449

465-
$iterator = new RecursiveIteratorIterator(new RecursiveDirectoryIterator(SRCDIR));
466-
$regex = new RegexIterator($iterator, '/^.+\.c$/i', RecursiveRegexIterator::GET_MATCH);
450+
function populateFromParent($classDoc, $doc) {
451+
if (empty(trim($doc["comment"]))) {
452+
$classComment = $classDoc->getParentClassComment();
453+
$doc["comment"] = $classComment !== null ? $classComment : "";
454+
}
455+
if (isset($doc["methods"])) {
456+
foreach ($doc["methods"] as $methodName => &$methodDoc) {
457+
if (empty(trim($methodDoc["comment"]))) {
458+
$methodComment = $classDoc->getParentMethodComment($methodName);
459+
$methodDoc["comment"] = $methodComment !== null ? $methodComment : "";
460+
}
461+
462+
if (isset($methodDoc["return"])) {
463+
$returnDoc = $methodDoc["return"];
464+
$parentReturnDoc = $classDoc->getParentReturnDoc($methodName);
465+
if ($parentReturnDoc !== null &&
466+
empty(trim($returnDoc["comment"])) &&
467+
($returnDoc["type"] == "mixed" || $returnDoc["type"] == $parentReturnDoc["type"])) {
468+
$methodDoc["return"]["type"] = $parentReturnDoc["type"];
469+
$methodDoc["return"]["comment"] = $parentReturnDoc["comment"];
470+
}
471+
}
467472

468-
foreach ($regex as $fileName => $notused) {
469-
$yamlFileName = preg_replace("/(.+)\.c$/", "$1.yaml", $fileName);
470-
$fileName = substr($fileName, strlen(SRCDIR));
471-
$fileName = preg_replace("/(.+)\.c$/", "$1", $fileName);
473+
if (isset($methodDoc["params"])) {
474+
foreach ($methodDoc["params"] as $paramName => $paramDoc) {
475+
$parentParamDoc = $classDoc->getParentParamDoc($methodName, $paramName);
476+
if ($parentParamDoc !== null &&
477+
empty(trim($paramDoc["comment"])) &&
478+
($paramDoc["type"] == "mixed" || $paramDoc["type"] == $parentParamDoc["type"])) {
479+
$methodDoc["params"][$paramName]["type"] = $parentParamDoc["type"];
480+
$methodDoc["params"][$paramName]["comment"] = $parentParamDoc["comment"];
481+
}
482+
}
483+
}
484+
}
485+
}
472486

473-
if ($fileName == "/Core") {
474-
$fileName = "/" . INPUT_NAMESPACE;
487+
return $doc;
488+
}
489+
490+
YamlClassDoc::loadAll(SRCDIR);
491+
492+
foreach(YamlClassDoc::getClassDocs() as $classDoc) {
493+
$fileName = $classDoc->getFileName();
494+
$yamlFileName = $classDoc->getYamlFileName();
495+
$class = $classDoc->getClass();
496+
$classNameNoCoreNamespace = $classDoc->getClassNameWithNoCoreNamespace();
497+
$doc = populateFromParent($classDoc, $classDoc->getDoc());
498+
499+
if ($fileName == "/". INPUT_NAMESPACE) {
475500
$fullClassName = str_replace("/", "\\", $fileName);
476501
$namespaceDirectory = DOCDIR . "/" . dirname($fileName);
477502
} else {
478503
$fullClassName = INPUT_NAMESPACE . str_replace("/", "\\", $fileName);
479504
$namespaceDirectory = DOCDIR . "/" . OUTPUT_NAMESPACE . dirname($fileName);
480505
}
481506

482-
try {
483-
if (!is_dir($namespaceDirectory)) {
484-
if (!mkdir($namespaceDirectory, 0777, true)) {
485-
die("Unable to create directory '$namespaceDirectory'" . PHP_EOL);
486-
}
507+
if (!is_dir($namespaceDirectory)) {
508+
if (!mkdir($namespaceDirectory, 0777, true)) {
509+
die("Unable to create directory '$namespaceDirectory'" . PHP_EOL);
487510
}
511+
}
488512

489-
$class = new ReflectionClass($fullClassName);
513+
$className = $class->getShortName();
490514

491-
$className = $class->getShortName();
515+
$stubFileName = rtrim($namespaceDirectory, "/") . "/$className.php";
516+
echo "Generating stub for '$fullClassName' ($yamlFileName --> $stubFileName)" . PHP_EOL;
517+
if(!($file = fopen($stubFileName, "w"))) {
518+
die("Unable to create file '$stubFileName'" . PHP_EOL);
519+
}
492520

493-
$stubFileName = rtrim($namespaceDirectory, "/") . "/$className.php";
494-
echo "Generating stub for '$fullClassName' ($yamlFileName --> $stubFileName)" . PHP_EOL;
495-
if(!($file = fopen($stubFileName, "w"))) {
496-
die("Unable to create file '$stubFileName'" . PHP_EOL);
497-
}
521+
fwrite($file, "<?php" . PHP_EOL);
522+
fwrite($file, PHP_EOL);
523+
fwrite($file, LICENSE_COMMENT . PHP_EOL);
524+
fwrite($file, PHP_EOL);
498525

499-
fwrite($file, "<?php" . PHP_EOL);
500-
fwrite($file, PHP_EOL);
501-
fwrite($file, LICENSE_COMMENT . PHP_EOL);
526+
$namespace = $class->getNamespaceName();
527+
if ($namespace) {
528+
fwrite($file, "namespace $namespace;" . PHP_EOL);
502529
fwrite($file, PHP_EOL);
530+
}
503531

504-
$namespace = $class->getNamespaceName();
505-
if ($namespace) {
506-
fwrite($file, "namespace $namespace;" . PHP_EOL);
507-
fwrite($file, PHP_EOL);
508-
}
509-
510-
$doc = yaml_parse_file($yamlFileName);
511-
512-
if ($doc === false) {
513-
logWarning("Unable to open doc yaml file '$yamlFileName'");
514-
}
515-
516-
$classNameNoCoreNamespace = preg_replace("/" . INPUT_NAMESPACE . "\\\\/", "", $class->getName());
517-
518-
if (isset($doc[$classNameNoCoreNamespace]) && $classNameNoCoreNamespace != $class->getName()) {
519-
$doc[$class->getName()] = $doc[$classNameNoCoreNamespace];
520-
unset($doc[$classNameNoCoreNamespace]);
521-
}
532+
if ($classNameNoCoreNamespace === $class->getName()) {
533+
$doc = array($classNameNoCoreNamespace => $doc);
534+
} else {
535+
$doc = array($class->getName() => $doc);
536+
}
522537

523-
writeClass($doc, $file, $class);
538+
writeClass($doc, $file, $class);
524539

525-
fclose($file);
540+
fclose($file);
526541

527-
exec(PHP_SYNTAX_CHECK . " $stubFileName", $syntaxCheckOutput, $syntaxCheckReturnVar);
528-
if ($syntaxCheckReturnVar !== 0) {
529-
$syntaxCheckOutput = implode(PHP_EOL, $syntaxCheckOutput);
530-
die("Syntax invalid for '$fullClassName' ($stubFileName): $syntaxCheckOutput" . PHP_EOL);
531-
}
532-
} catch(ReflectionException $e) {
533-
logWarning("Ignoring '$fullClassName': $e");
542+
exec(PHP_SYNTAX_CHECK . " $stubFileName", $syntaxCheckOutput, $syntaxCheckReturnVar);
543+
if ($syntaxCheckReturnVar !== 0) {
544+
$syntaxCheckOutput = implode(PHP_EOL, $syntaxCheckOutput);
545+
die("Syntax invalid for '$fullClassName' ($stubFileName): $syntaxCheckOutput" . PHP_EOL);
534546
}
535547
}

0 commit comments

Comments
 (0)