APIDOC beautification

extensions/apidoc/models/FunctionDoc.php

@@ -73,7 +73,7 @@ class FunctionDoc extends BaseDoc
 			} elseif ($tag instanceof ReturnTag) {
 				$this->returnType = $tag->getType();
 				$this->returnTypes = $tag->getTypes();
-				$this->return = $tag->getDescription();
+				$this->return = ucfirst($tag->getDescription());
 				unset($this->tags[$i]);
 			}
 		}

extensions/apidoc/renderers/BaseRenderer.php

@@ -57,9 +57,10 @@ abstract class BaseRenderer extends Component
 	 * @param ClassDoc|InterfaceDoc|TraitDoc|ClassDoc[]|InterfaceDoc[]|TraitDoc[] $types
 	 * @param string $title a title to be used for the link TODO check whether [[yii\...|Class]] is supported
 	 * @param BaseDoc $context
+	 * @param array $options additional HTML attributes for the link.
 	 * @return string
 	 */
-	public function createTypeLink($types, $context = null, $title = null)
+	public function createTypeLink($types, $context = null, $title = null, $options = [])
 	{
 		if (!is_array($types)) {
 			$types = [$types];
@@ -103,9 +104,9 @@ abstract class BaseRenderer extends Component
 				// check if it is PHP internal class
 				if (((class_exists($type, false) || interface_exists($type, false) || trait_exists($type, false)) &&
 					($reflection = new \ReflectionClass($type)) && $reflection->isInternal())) {
-					$links[] = $this->generateLink($linkText, 'http://www.php.net/class.' . strtolower(ltrim($type, '\\'))) . $postfix;
+					$links[] = $this->generateLink($linkText, 'http://www.php.net/class.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
 				} elseif (in_array($type, $phpTypes)) {
-					$links[] = $this->generateLink($linkText, 'http://www.php.net/language.types.' . strtolower(ltrim($type, '\\'))) . $postfix;
+					$links[] = $this->generateLink($linkText, 'http://www.php.net/language.types.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
 				} else {
 					$links[] = $type;
 				}
@@ -114,7 +115,7 @@ abstract class BaseRenderer extends Component
 				if ($title !== null) {
 					$linkText = $title;
 				}
-				$links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name)) . $postfix;
+				$links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name), $options) . $postfix;
 			}
 		}
 		return implode('|', $links);
@@ -125,9 +126,10 @@ abstract class BaseRenderer extends Component
 	 * creates a link to a subject
 	 * @param PropertyDoc|MethodDoc|ConstDoc|EventDoc $subject
 	 * @param string $title
+	 * @param array $options additional HTML attributes for the link.
 	 * @return string
 	 */
-	public function createSubjectLink($subject, $title = null)
+	public function createSubjectLink($subject, $title = null, $options = [])
 	{
 		if ($title === null) {
 			if ($subject instanceof MethodDoc) {
@@ -146,7 +148,7 @@ abstract class BaseRenderer extends Component
 				$link .= '#' . $subject->name;
 			}
 			$link .= '-detail';
-			return Html::a($title, null, ['href' => $link]);
+			return $this->generateLink($title, $link, $options);
 		}
 	}
 
@@ -175,9 +177,10 @@ abstract class BaseRenderer extends Component
 	 * generate link markup
 	 * @param $text
 	 * @param $href
+	 * @param array $options additional HTML attributes for the link.
 	 * @return mixed
 	 */
-	protected abstract function generateLink($text, $href);
+	protected abstract function generateLink($text, $href, $options = []);
 
 	/**
 	 * Generate an url to a type in apidocs

extensions/apidoc/templates/bootstrap/assets/css/style.css

@@ -3,6 +3,10 @@ body {
 	height: 100%;
 }
 
+.guide-content, .api-content {
+	max-width: 1250px;
+}
+
 .wrap {
 	min-height: 100%;
 	height: auto;
@@ -35,9 +39,14 @@ body {
 	color: #fff;
 }
 
-.signature, .signature2 {
+.signature, .table-striped > tbody > tr > td.signature {
-	padding: 3px;
+	margin: 10px 0 10px 0;
+	padding: 8px;
+
 	color: #000000;
+	background: rgba(230, 236, 255, 0.81);
+	border: 1px rgba(191, 207, 255, 0.81) solid;
+
 	font-family: "courier new", "times new roman", monospace;
 	line-height: 1.3em;
 	white-space: pre-line;
@@ -45,12 +54,6 @@ body {
 	word-break: break-all;
 }
 
-.signature {
-	margin: 10px 0 10px 0;
-	background: #E6ECFF;
-	border: 1px #BFCFFF solid;
-}
-
 blockquote {
 	font-size: 14px;
 }
@@ -59,7 +62,50 @@ td p {
 	margin: 0;
 }
 
-table.detailTable .paramNameCol { width: 15%; min-width: 100px; }
+table.detail-table .param-name-col { width: 15%; min-width: 100px; }
-table.detailTable .paramTypeCol { width: 15%; min-width: 150px; }
+table.detail-table .param-type-col { width: 15%; min-width: 150px; }
-table.detailTable .paramDescCol { width: 70%; }
+table.detail-table .param-desc-col { width: 70%; }
 
+table.summary-table .col-method   { width: 20%; }
+table.summary-table .col-property { width: 20%; }
+table.summary-table .col-const    { width: 20%; }
+table.summary-table .col-event    { width: 20%; }
+table.summary-table .col-defined  { width: 15%; }
+
+.detail-header {
+	margin-top: 30px;
+}
+
+.doc-description {
+	border-left: solid 1px #ddd;
+	border-right: solid 1px #ddd;
+	padding: 10px 8px;
+	margin: 0;
+}
+
+.event-doc .doc-description {
+	border-bottom: solid 1px #ddd;
+}
+
+.doc-description p:last-child {
+	margin-bottom: 0;
+}
+
+.tool-link {
+	float: right;
+	color: #ddd;
+	margin: 0 8px;
+}
+
+.icon-hash:before {
+	content: '#';
+	font-size: 32px;
+	font-weight: bold;
+	/*top: -10px;*/
+	line-height: 0.5;
+}
+
+.tool-link:hover {
+	color: #bbb;
+	text-decoration: none;
+}

extensions/apidoc/templates/bootstrap/layouts/api.php

@@ -44,7 +44,7 @@ $this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
 			'view' => $this,
 		])?>
 	</div>
-	<div class="col-md-9" role="main">
+	<div class="col-md-9 api-content" role="main">
 		<?= $content ?>
 	</div>
 </div>

extensions/apidoc/templates/bootstrap/layouts/guide.php

@@ -32,7 +32,7 @@ $this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
 			'view' => $this,
 		]) ?>
 	</div>
-	<div class="col-md-9" role="main">
+	<div class="col-md-9 guide-content" role="main">
 		<?= $content ?>
 	</div>
 </div>

extensions/apidoc/templates/html/ApiRenderer.php

@@ -246,8 +246,8 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
 
 		return ($method->isReturnByReference ? '<b>&</b>' : '')
 			. ($method->returnType === null ? 'void' : $this->createTypeLink($method->returnTypes))
-			. ' ' . $this->createSubjectLink($method, $method->name)
+			. ' <strong>' . $this->createSubjectLink($method, $method->name) . '</strong>'
-			. ApiMarkdown::highlight('( ' . implode(', ', $params) . ' )', 'php');
+			. ApiMarkdown::highlight(str_replace('  ', ' ', '( ' . implode(', ', $params) . ' )'), 'php');
 	}
 
 	public function generateApiUrl($typeName)
@@ -271,14 +271,12 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
 	}
 
 	/**
-	 * generate link markup
+	 * @inheritdoc
-	 * @param $text
-	 * @param $href
-	 * @return mixed
 	 */
-	protected function generateLink($text, $href)
+	protected function generateLink($text, $href, $options = [])
 	{
-		return Html::a($text, null, ['href' => $href]);
+		$options['href'] = $href;
+		return Html::a($text, null, $options);
 	}
 
 	public function getSourceUrl($type)

extensions/apidoc/templates/html/GuideRenderer.php

@@ -138,14 +138,12 @@ abstract class GuideRenderer extends BaseGuideRenderer
 	}
 
 	/**
-	 * generate link markup
+	 * @inheritdoc
-	 * @param $text
-	 * @param $href
-	 * @return mixed
 	 */
-	protected function generateLink($text, $href)
+	protected function generateLink($text, $href, $options = [])
 	{
-		return Html::a($text, null, ['href' => $href]);
+		$options['href'] = $href;
+		return Html::a($text, null, $options);
 	}
 
 	/**

extensions/apidoc/templates/html/views/constSummary.php

@@ -18,14 +18,15 @@ if (empty($type->constants)) {
 $constants = $type->constants;
 ArrayHelper::multisort($constants, 'name');
 ?>
-<div class="summary docConst">
+<div class="summary doc-const">
 	<h2>Constants</h2>
 
 	<p><a href="#" class="toggle">Hide inherited constants</a></p>
 
-<table class="summaryTable table table-striped table-bordered table-hover">
+	<table class="summary-table table table-striped table-bordered table-hover">
 	<colgroup>
 		<col class="col-const" />
+		<col class="col-value" />
 		<col class="col-description" />
 		<col class="col-defined" />
 	</colgroup>

extensions/apidoc/templates/html/views/eventDetails.php

@@ -7,8 +7,11 @@ use yii\helpers\ArrayHelper;
 /**
  * @var ClassDoc $type
  * @var yii\web\View $this
+ * @var \yii\apidoc\templates\html\ApiRenderer $renderer
  */
 
+$renderer = $this->context;
+
 $events = $type->getNativeEvents();
 if (empty($events)) {
 	return;
@@ -16,10 +19,24 @@ if (empty($events)) {
 ArrayHelper::multisort($events, 'name');
 ?>
 <h2>Event Details</h2>
+
+<div class="event-doc">
 <?php foreach ($events as $event): ?>
-	<div class="detailHeader h3" id="<?= $event->name.'-detail' ?>">
+	<div class="detail-header h3" id="<?= $event->name.'-detail' ?>">
+		<a href="#" class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
+		<?= $renderer->createSubjectLink($event, '<span class="glyphicon icon-hash"></span>', [
+			'title' => 'direct link to this method',
+			'class' => 'tool-link hash',
+		]) ?>
+
+		<?php if (($sourceUrl = $renderer->getSourceUrl($event->definedBy, $event->startLine)) !== null): ?>
+			<a href="<?= str_replace('/blob/', '/edit/', $sourceUrl) ?>" class="tool-link" title="edit on github"><span class="glyphicon glyphicon-pencil"></span></a>
+			<a href="<?= $sourceUrl ?>" class="tool-link" title="view source on github"><span class="glyphicon glyphicon-eye-open"></span></a>
+		<?php endif; ?>
+
+
 		<?= $event->name ?>
-		<span class="detailHeaderTag small">
+		<span class="detail-header-tag small">
 		event
 		<?php if (!empty($event->since)): ?>
 			(available since version <?= $event->since ?>)
@@ -27,13 +44,11 @@ ArrayHelper::multisort($events, 'name');
 		</span>
 	</div>
 
-	<?php /*
+	<div class="doc-description">
-	<div class="signature">
-		<?php echo $event->trigger->signature; ?>
-	</div>*/ ?>
-
 		<?= ApiMarkdown::process($event->description, $type) ?>
 
 		<?= $this->render('seeAlso', ['object' => $event]) ?>
+	</div>
 
 <?php endforeach; ?>
+</div>

extensions/apidoc/templates/html/views/eventSummary.php

@@ -18,14 +18,15 @@ if (empty($type->events)) {
 $events = $type->events;
 ArrayHelper::multisort($events, 'name');
 ?>
-<div class="summary docEvent">
+<div class="summary doc-event">
 	<h2>Events</h2>
 
 	<p><a href="#" class="toggle">Hide inherited events</a></p>
 
-<table class="summaryTable table table-striped table-bordered table-hover">
+	<table class="summary-table table table-striped table-bordered table-hover">
 	<colgroup>
 		<col class="col-event" />
+		<col class="col-type" />
 		<col class="col-description" />
 		<col class="col-defined" />
 	</colgroup>

extensions/apidoc/templates/html/views/methodDetails.php

@@ -21,11 +21,23 @@ ArrayHelper::multisort($methods, 'name');
 ?>
 <h2>Method Details</h2>
 
+<div class="method-doc">
 <?php foreach ($methods as $method): ?>
 
-	<div class="detailHeader h3" id="<?= $method->name . '()-detail' ?>">
+	<div class="detail-header h3" id="<?= $method->name . '()-detail' ?>">
+		<a href="#" class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
+		<?= $renderer->createSubjectLink($method, '<span class="glyphicon icon-hash"></span>', [
+			'title' => 'direct link to this method',
+			'class' => 'tool-link hash',
+		]) ?>
+
+		<?php if (($sourceUrl = $renderer->getSourceUrl($method->definedBy, $method->startLine)) !== null): ?>
+			<a href="<?= str_replace('/blob/', '/edit/', $sourceUrl) ?>" class="tool-link" title="edit on github"><span class="glyphicon glyphicon-pencil"></span></a>
+			<a href="<?= $sourceUrl ?>" class="tool-link" title="view source on github"><span class="glyphicon glyphicon-eye-open"></span></a>
+		<?php endif; ?>
+
 		<?= $method->name ?>()
-		<span class="detailHeaderTag small">
+		<span class="detail-header-tag small">
 			<?= $method->visibility ?>
 			method
 			<?php if (!empty($method->since)): ?>
@@ -34,45 +46,42 @@ ArrayHelper::multisort($methods, 'name');
 		</span>
 	</div>
 
-	<table class="detailTable table table-striped table-bordered table-hover">
+	<div class="doc-description">
-		<tr><td colspan="3">
+		<p><strong><?= ApiMarkdown::process($method->shortDescription, $type, true) ?></strong></p>
-			<div class="signature2"><?= $renderer->renderMethodSignature($method) ?></div>
+
-		</td></tr>
+		<?= ApiMarkdown::process($method->description, $type) ?>
+
+		<?= $this->render('seeAlso', ['object' => $method]) ?>
+	</div>
+
+	<table class="detail-table table table-striped table-bordered table-hover">
+		<tr><td colspan="3" class="signature"><?= $renderer->renderMethodSignature($method) ?></td></tr>
 		<?php if (!empty($method->params) || !empty($method->return) || !empty($method->exceptions)): ?>
 			<?php foreach ($method->params as $param): ?>
 				<tr>
-				  <td class="paramNameCol"><?= ApiMarkdown::highlight($param->name, 'php') ?></td>
+				  <td class="param-name-col"><?= ApiMarkdown::highlight($param->name, 'php') ?></td>
-				  <td class="paramTypeCol"><?= $renderer->createTypeLink($param->types) ?></td>
+				  <td class="param-type-col"><?= $renderer->createTypeLink($param->types) ?></td>
-				  <td class="paramDescCol"><?= ApiMarkdown::process($param->description, $type) ?></td>
+				  <td class="param-desc-col"><?= ApiMarkdown::process($param->description, $type) ?></td>
 				</tr>
 			<?php endforeach; ?>
 			<?php if (!empty($method->return)): ?>
 				<tr>
-				  <th class="paramNameCol"><?= 'return' ?></th>
+				  <th class="param-name-col">return</th>
-				  <td class="paramTypeCol"><?= $renderer->createTypeLink($method->returnTypes) ?></td>
+				  <td class="param-type-col"><?= $renderer->createTypeLink($method->returnTypes) ?></td>
-				  <td class="paramDescCol"><?= ApiMarkdown::process($method->return, $type) ?></td>
+				  <td class="param-desc-col"><?= ApiMarkdown::process($method->return, $type) ?></td>
 				</tr>
 			<?php endif; ?>
 			<?php foreach ($method->exceptions as $exception => $description): ?>
 				<tr>
-				  <th class="paramNameCol"><?= 'throws' ?></th>
+				  <th class="param-name-col">throws</th>
-				  <td class="paramTypeCol"><?= $renderer->createTypeLink($exception) ?></td>
+				  <td class="param-type-col"><?= $renderer->createTypeLink($exception) ?></td>
-				  <td class="paramDescCol"><?= ApiMarkdown::process($description, $type) ?></td>
+				  <td class="param-desc-col"><?= ApiMarkdown::process($description, $type) ?></td>
 				</tr>
 			<?php endforeach; ?>
 		<?php endif; ?>
-		<?php if (($sourceUrl = $renderer->getSourceUrl($method->definedBy, $method->startLine)) !== null): ?>
-			<tr>
-				<td colspan="3">Source Code: <a href="<?= $sourceUrl ?>"><?= $sourceUrl ?></a></td>
-			</tr>
-		<?php endif; ?>
 	</table>
 
 <!--	--><?php //$this->renderPartial('sourceCode',array('object'=>$method)); ?>
 
-	<p><strong><?= ApiMarkdown::process($method->shortDescription, $type, true) ?></strong></p>
-	<?= ApiMarkdown::process($method->description, $type) ?>
-
-	<?= $this->render('seeAlso', ['object' => $method]) ?>
-
 <?php endforeach; ?>
+</div>

extensions/apidoc/templates/html/views/methodSummary.php

@@ -19,12 +19,12 @@ if ($protected && count($type->getProtectedMethods()) == 0 || !$protected && cou
 	return;
 } ?>
 
-<div class="summary docMethod">
+<div class="summary doc-method">
 <h2><?= $protected ? 'Protected Methods' : 'Public Methods' ?></h2>
 
 <p><a href="#" class="toggle">Hide inherited methods</a></p>
 
-<table class="summaryTable table table-striped table-bordered table-hover">
+<table class="summary-table table table-striped table-bordered table-hover">
 <colgroup>
 	<col class="col-method" />
 	<col class="col-description" />

extensions/apidoc/templates/html/views/propertyDetails.php

@@ -21,9 +21,22 @@ ArrayHelper::multisort($properties, 'name');
 ?>
 <h2>Property Details</h2>
 
+<div class="property-doc">
 <?php foreach ($properties as $property): ?>
 
-	<div class="detailHeader h3" id="<?= $property->name.'-detail' ?>">
+	<div class="detail-header h3" id="<?= $property->name.'-detail' ?>">
+		<a href="#" class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
+		<?= $renderer->createSubjectLink($property, '<span class="glyphicon icon-hash"></span>', [
+			'title' => 'direct link to this method',
+			'class' => 'tool-link hash',
+		]) ?>
+
+		<?php if (($sourceUrl = $renderer->getSourceUrl($property->definedBy, $property->startLine)) !== null): ?>
+			<a href="<?= str_replace('/blob/', '/edit/', $sourceUrl) ?>" class="tool-link" title="edit on github"><span class="glyphicon glyphicon-pencil"></span></a>
+			<a href="<?= $sourceUrl ?>" class="tool-link" title="view source on github"><span class="glyphicon glyphicon-eye-open"></span></a>
+		<?php endif; ?>
+
+
 		<?= $property->name ?>
 		<span class="detailHeaderTag small">
 			<?= $property->visibility ?>
@@ -43,3 +56,4 @@ ArrayHelper::multisort($properties, 'name');
 	<?= $this->render('seeAlso', ['object' => $property]) ?>
 
 <?php endforeach; ?>
+</div>

extensions/apidoc/templates/html/views/propertySummary.php

@@ -18,12 +18,12 @@ if ($protected && count($type->getProtectedProperties()) == 0 || !$protected &&
 	return;
 } ?>
 
-<div class="summary docProperty">
+<div class="summary doc-property">
 <h2><?= $protected ? 'Protected Properties' : 'Public Properties' ?></h2>
 
 <p><a href="#" class="toggle">Hide inherited properties</a></p>
 
-<table class="summaryTable table table-striped table-bordered table-hover">
+<table class="summary-table table table-striped table-bordered table-hover">
 <colgroup>
 	<col class="col-property" />
 	<col class="col-type" />

extensions/apidoc/templates/html/views/seeAlso.php

@@ -11,21 +11,22 @@ foreach ($object->tags as $tag) {
 	if (get_class($tag) == 'phpDocumentor\Reflection\DocBlock\Tag\SeeTag') {
 		$ref = $tag->getReference();
 		if (strpos($ref, '://') === false) {
-			$see[] = '[[' . $ref . ']]';
+			$ref = '[[' . $ref . ']]';
-		} else {
-			$see[] = $ref;
 		}
+		$see[] = rtrim(\yii\apidoc\helpers\ApiMarkdown::process($ref . ' ' . $tag->getDescription(), $object->definedBy, true), ". \r\n");
 	}
 }
 if (empty($see)) {
 	return;
+} elseif (count($see) == 1) {
+	echo '<p>See also ' . reset($see) . '.</p>';
+} else {
+	echo '<p>See also:</p><ul>';
+	foreach ($see as $ref) {
+		if (substr($ref, -1, 1) != '>') {
+			$ref .= '.';
+		}
+		echo "<li>$ref</li>";
+	}
+	echo '</ul>';
 }
-?>
-<div class="SeeAlso">
-<h4>See Also</h4>
-<ul>
-<?php foreach ($see as $ref): ?>
-	<li><?= \yii\apidoc\helpers\ApiMarkdown::process($ref, $object->definedBy, true) ?></li>
-<?php endforeach; ?>
-</ul>
-</div>