Fix #140: Added support for multiple "since" tags

CHANGELOG.md

@@ -25,6 +25,7 @@ Yii Framework 2 apidoc extension Change Log
 - Enh #196: Added support for PHPDoc inline links (arogachev)
 - Enh #147: Added feature of viewing method source code without external links (arogachev)
 - Bug #168: Fixed handling of inheritance (arogachev)
+- Enh #140: Added support for multiple "since" tags (arogachev)
 - Bug #240: Fixed a bug when a "virtual" / "magic" property's full description was displayed instead of preview in 
   properties list (arogachev)
 - Bug #239: Do not show a "virtual" / "magic" methods's full description if it matches short description (arogachev)

models/BaseDoc.php

@@ -36,7 +36,14 @@ class BaseDoc extends BaseObject
     public $endLine;
     public $shortDescription;
     public $description;
+    /**
+     * @var string|null Available since this version.
+     */
     public $since;
+    /**
+     * @var array A mapping where keys are versions and values are descriptions.
+     */
+    public $sinceMap = [];
     public $deprecatedSince;
     public $deprecatedReason;
     /**
@@ -183,11 +190,19 @@ public function __construct($reflector = null, $context = null, $config = [])
         $this->tags = $docBlock->getTags();
         foreach ($this->tags as $i => $tag) {
             if ($tag instanceof Since) {
-                $this->since = $tag->getVersion();
+                $description = (string) $tag->getDescription();
+                if (!$this->since && !$this->sinceMap && !$description) {
+                    $this->since = $tag->getVersion();
+                }
+
+                if ($description) {
+                    $this->sinceMap[$tag->getVersion()] = $description;
+                }
+
                 unset($this->tags[$i]);
             } elseif ($tag instanceof Deprecated) {
                 $this->deprecatedSince = $tag->getVersion();
-                $this->deprecatedReason = $tag->getDescription();
+                $this->deprecatedReason = (string) $tag->getDescription();
                 unset($this->tags[$i]);
             } elseif ($tag->getName() === 'todo') {
                 $this->todos[] = $tag;

templates/bootstrap/assets/css/style.css

@@ -274,6 +274,12 @@ tr.deprecated th {
     background: lightpink;
 }
 
+/* Changelog */
+
+.changelog {
+    border: 1px solid #ddd !important;
+}
+
 /* Todos */
 
 .todo {

templates/html/views/changelog.php

@@ -0,0 +1,25 @@
+<?php
+
+use yii\apidoc\models\BaseDoc;
+
+/* @var $doc BaseDoc */
+?>
+
+<?php if ($doc->sinceMap) { ?>
+    <table class="changelog table table-bordered">
+        <thead>
+            <tr>
+                <th scope="col">Version</th>
+                <th scope="col">Description</th>
+            </tr>
+        </thead>
+        <tbody>
+            <?php foreach ($doc->sinceMap as $version => $description) { ?>
+                <tr>
+                    <th><?= $version ?></th>
+                    <td><?= $description ?></td>
+                </tr>
+            <?php } ?>
+        </tbody>
+    </table>
+<?php } ?>

templates/html/views/eventDetails.php

@@ -57,5 +57,7 @@
         <?= $this->render('seeAlso', ['object' => $event]) ?>
     </div>
 
+    <?= $this->render('@yii/apidoc/templates/html/views/changelog', ['doc' => $event]) ?>
+
 <?php endforeach; ?>
 </div>

templates/html/views/methodDetails.php

@@ -91,25 +91,11 @@
         <?php endif; ?>
     </table>
 
-    <?php
-    $sourceCode = $method->sourceCode;
-    $collapseId = 'collapse' . ucfirst($method->name);
-    ?>
-
-    <p>
-        <a class="btn btn-link" data-toggle="collapse" href="#<?= $collapseId ?>" role="button" aria-expanded="false"
-           aria-controls="<?= $collapseId ?>">
-            Source code
-        </a>
-    </p>
-    <div class="collapse" id="<?= $collapseId ?>">
-        <div class="card card-body">
-            <pre>
-                <code class="hljs php language-php"><?= $highlighter->highlight('php', $sourceCode)->value ?></code>
-            </pre>
-        </div>
-    </div>
-
+    <?= $this->render('@yii/apidoc/templates/html/views/changelog', ['doc' => $method]) ?>
+    <?= $this->render(
+        '@yii/apidoc/templates/html/views/methodSourceCode',
+        ['method' => $method, 'highlighter' => $highlighter]
+    ) ?>
     <?= $this->render('@yii/apidoc/templates/html/views/todos', ['doc' => $method]) ?>
 
 <?php endforeach; ?>

templates/html/views/methodSourceCode.php

@@ -0,0 +1,24 @@
+<?php
+
+use yii\apidoc\models\MethodDoc;
+
+/* @var $method MethodDoc */
+/* @var $highlighter \Highlight\Highlighter */
+
+$sourceCode = $method->sourceCode;
+$collapseId = 'collapse' . ucfirst($method->name);
+?>
+
+<p>
+    <a class="btn btn-link" data-toggle="collapse" href="#<?= $collapseId ?>" role="button" aria-expanded="false"
+       aria-controls="<?= $collapseId ?>">
+        Source code
+    </a>
+</p>
+<div class="collapse" id="<?= $collapseId ?>">
+    <div class="card card-body">
+        <pre>
+            <code class="hljs php language-php"><?= $highlighter->highlight('php', $sourceCode)->value ?></code>
+        </pre>
+    </div>
+</div>

templates/html/views/propertyDetails.php

@@ -64,6 +64,7 @@
 
     <div class="signature"><?php echo $renderer->renderPropertySignature($property, $type); ?></div>
 
+    <?= $this->render('@yii/apidoc/templates/html/views/changelog', ['doc' => $property]) ?>
     <?= $this->render('@yii/apidoc/templates/html/views/todos', ['doc' => $property]) ?>
 
 <?php endforeach; ?>

templates/html/views/type.php

@@ -91,6 +91,8 @@
     <?= $this->render('seeAlso', ['object' => $type]) ?>
 </div>
 
+<?= $this->render('@yii/apidoc/templates/html/views/changelog', ['doc' => $type]) ?>
+
 <a id="properties"></a>
 <?= $this->render('@yii/apidoc/templates/html/views/propertySummary', ['type' => $type, 'protected' => false]) ?>
 <?= $this->render('@yii/apidoc/templates/html/views/propertySummary', ['type' => $type, 'protected' => true]) ?>