fixed apidoc short description

fixes yiisoft#2797
alexk984 · May 25, 2014 · 85f49e0 · 85f49e0
1 parent e3ee1b0
commit 85f49e0
Show file tree

Hide file tree

Showing 6 changed files with 27 additions and 17 deletions.
diff --git a/extensions/apidoc/models/BaseDoc.php b/extensions/apidoc/models/BaseDoc.php
@@ -127,4 +127,20 @@ public function __construct($reflector = null, $context = null, $config = [])
 //		$lines = file(YII_PATH . $this->sourcePath);
 //		return implode("", array_slice($lines, $this->startLine - 1, $this->endLine - $this->startLine + 1));
 //	}
+
+    public static function extractFirstSentence($text)
+    {
+        if (mb_strlen($text) > 4 && ($pos = mb_strpos($text, '.', 4, 'utf-8')) !== false) {
+            $sentence = mb_substr($text, 0, $pos + 1, 'utf-8');
+            if (mb_strlen($text) >= $pos + 3) {
+                $abbrev = mb_substr($text, $pos - 1, 4);
+                if ($abbrev === 'e.g.' || $abbrev === 'i.e.') { // do not break sentence after abbreviation
+                    $sentence .= static::extractFirstSentence(mb_substr($text, $pos + 1));
+                }
+            }
+            return $sentence;
+        } else {
+            return $text;
+        }
+    }
 }
diff --git a/extensions/apidoc/models/Context.php b/extensions/apidoc/models/Context.php
@@ -289,8 +289,7 @@ protected function handlePropertyFeature($class)
                         'isStatic' => false,
                         'type' => $method->returnType,
                         'types' => $method->returnTypes,
-                        'shortDescription' => (($pos = strpos($method->return, '.')) !== false) ?
-                                substr($method->return, 0, $pos) : $method->return,
+                        'shortDescription' => BaseDoc::extractFirstSentence($method->return),
                         'description' => $method->return,
                         'getter' => $method
                         // TODO set default value
@@ -319,8 +318,7 @@ protected function handlePropertyFeature($class)
                         'isStatic' => false,
                         'type' => $param->type,
                         'types' => $param->types,
-                        'shortDescription' => (($pos = strpos($param->description, '.')) !== false) ?
-                                substr($param->description, 0, $pos) : $param->description,
+                        'shortDescription' => BaseDoc::extractFirstSentence($param->description),
                         'description' => $param->description,
                         'setter' => $method
                     ]);

diff --git a/extensions/apidoc/models/EventDoc.php b/extensions/apidoc/models/EventDoc.php
@@ -39,11 +39,7 @@ public function __construct($reflector = null, $context = null, $config = [])
                 $this->type = $eventTag->getType();
                 $this->types = $eventTag->getTypes();
                 $this->description = ucfirst($eventTag->getDescription());
-                if (($pos = strpos($this->description, '.')) !== false) {
-                    $this->shortDescription = substr($this->description, 0, $pos);
-                } else {
-                    $this->shortDescription = $this->description;
-                }
+                $this->shortDescription = BaseDoc::extractFirstSentence($this->description);
                 unset($this->tags[$i]);
             }
         }

diff --git a/extensions/apidoc/models/PropertyDoc.php b/extensions/apidoc/models/PropertyDoc.php
@@ -72,11 +72,7 @@ public function __construct($reflector = null, $context = null, $config = [])
                 $this->type = $tag->getType();
                 $this->types = $tag->getTypes();
                 $this->description = ucfirst($tag->getDescription());
-                if (($pos = strpos($this->description, '.')) !== false) {
-                    $this->shortDescription = substr($this->description, 0, $pos + 1);
-                } else {
-                    $this->shortDescription = $this->description;
-                }
+                $this->shortDescription = BaseDoc::extractFirstSentence($this->description);
             }
         }
         if (empty($this->shortDescription) && $context !== null && !$hasInheritdoc) {

diff --git a/extensions/apidoc/templates/html/views/seeAlso.php b/extensions/apidoc/templates/html/views/seeAlso.php
@@ -5,6 +5,8 @@
  * @var yii\web\View $this
  */
 
+$type = $object instanceof \yii\apidoc\models\TypeDoc ? $object : $object->definedBy;
+
 $see = [];
 foreach ($object->tags as $tag) {
     /** @var $tag phpDocumentor\Reflection\DocBlock\Tag\SeeTag */
@@ -13,7 +15,7 @@
         if (strpos($ref, '://') === false) {
             $ref = '[[' . $ref . ']]';
         }
-        $see[] = rtrim(\yii\apidoc\helpers\ApiMarkdown::process($ref . ' ' . $tag->getDescription(), $object->definedBy, true), ". \r\n");
+        $see[] = rtrim(\yii\apidoc\helpers\ApiMarkdown::process($ref . ' ' . $tag->getDescription(), $type, true), ". \r\n");
     }
 }
 if (empty($see)) {

diff --git a/extensions/apidoc/templates/html/views/type.php b/extensions/apidoc/templates/html/views/type.php
@@ -80,8 +80,10 @@
 </table>
 
 <div id="classDescription">
-    <strong><?= ApiMarkdown::process($type->shortDescription, $type, true) ?></strong>
-    <p><?= ApiMarkdown::process($type->description, $type) ?></p>
+    <p><strong><?= ApiMarkdown::process($type->shortDescription, $type, true) ?></strong></p>
+    <?= ApiMarkdown::process($type->description, $type) ?>
+
+    <?= $this->render('seeAlso', ['object' => $type]) ?>
 </div>
 
 <a name="properties"></a>