From 85f49e0cfe21a45a6a14b53cde18cab7832ef44d Mon Sep 17 00:00:00 2001
From: Carsten Brandt <mail@cebe.cc>
Date: Sun, 25 May 2014 22:26:21 +0200
Subject: [PATCH] fixed apidoc short description

fixes #2797
---
 extensions/apidoc/models/BaseDoc.php             | 16 ++++++++++++++++
 extensions/apidoc/models/Context.php             |  6 ++----
 extensions/apidoc/models/EventDoc.php            |  6 +-----
 extensions/apidoc/models/PropertyDoc.php         |  6 +-----
 .../apidoc/templates/html/views/seeAlso.php      |  4 +++-
 extensions/apidoc/templates/html/views/type.php  |  6 ++++--
 6 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/extensions/apidoc/models/BaseDoc.php b/extensions/apidoc/models/BaseDoc.php
index c20d9c9626..f64f475726 100644
--- a/extensions/apidoc/models/BaseDoc.php
+++ b/extensions/apidoc/models/BaseDoc.php
@@ -127,4 +127,20 @@ class BaseDoc extends Object
 //		$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
index 73ad142663..7416996401 100644
--- a/extensions/apidoc/models/Context.php
+++ b/extensions/apidoc/models/Context.php
@@ -289,8 +289,7 @@ class Context extends Component
                         '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 @@ class Context extends Component
                         '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
index 5e23b37383..d699d674f6 100644
--- a/extensions/apidoc/models/EventDoc.php
+++ b/extensions/apidoc/models/EventDoc.php
@@ -39,11 +39,7 @@ class EventDoc extends ConstDoc
                 $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
index 6712033804..8a7c88317c 100644
--- a/extensions/apidoc/models/PropertyDoc.php
+++ b/extensions/apidoc/models/PropertyDoc.php
@@ -72,11 +72,7 @@ class PropertyDoc extends BaseDoc
                 $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
index e244c2ef07..bb33e56cdf 100644
--- 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 @@ foreach ($object->tags as $tag) {
         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
index 74954a73d5..08a63cae22 100644
--- a/extensions/apidoc/templates/html/views/type.php
+++ b/extensions/apidoc/templates/html/views/type.php
@@ -80,8 +80,10 @@ $renderer = $this->context;
 </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>