From 03113662e4b1f4f53108e0bc957224e16acd1fef Mon Sep 17 00:00:00 2001
From: Stephen Sawchuk <sawchuk@gmail.com>
Date: Thu, 18 Sep 2014 21:33:01 -0400
Subject: [PATCH] docs: fix examples, style optionals

---
 docs/components/docs/docs.html    | 64 ++++++++++++++-----------------
 docs/components/docs/docs.js      | 15 +++++---
 docs/components/docs/history.html |  0
 docs/css/main.css                 | 12 +++++-
 4 files changed, 48 insertions(+), 43 deletions(-)
 delete mode 100644 docs/components/docs/history.html

diff --git a/docs/components/docs/docs.html b/docs/components/docs/docs.html
index 3e29d371551..8f3b9138ffa 100644
--- a/docs/components/docs/docs.html
+++ b/docs/components/docs/docs.html
@@ -22,16 +22,14 @@ <h1 class="page-title">{{pageTitle}}</h1>
 
   <section class="content">
     <article ng-show="showReference">
-    <h1>{{module[0].toUpperCase() + module.substr(1)}}</h1>
-    <h3 class="sub-heading">
-      <div class="toggler" ng-click="showGcloudDocs = !showGcloudDocs">
-        <span class="toggle" ng-hide="showGcloudDocs">▹</span>
-        <span class="toggle" ng-show="showGcloudDocs">▿</span>
-      </div>
-      Getting Started with <code>gcloud</code>
-    </h3>
+      <h3 class="sub-heading">
+        <div class="toggler" ng-click="showGcloudDocs = !showGcloudDocs">
+          <span class="toggle" ng-hide="showGcloudDocs">▹</span>
+          <span class="toggle" ng-show="showGcloudDocs">▿</span>
+        </div>
+        Getting Started with <code>gcloud</code>
+      </h3>
       <article ng-if="showGcloudDocs">
-        <h1>{{module[0].toUpperCase() + module.substr(1)}}</h1>
         <p>
           First, install <code>gcloud</code> with npm and require it into your project:
         </p>
@@ -59,40 +57,32 @@ <h1>{{module[0].toUpperCase() + module.substr(1)}}</h1>
         </p>
       </article>
       <hr>
+
       <article ng-if="isActiveDoc('datastore')">
-        <h2>Overview</h2>
+        <h3>Datastore Overview</h3>
         <p>
           The <code>gcloud.datastore</code> object gives you some convenience methods, as well as exposes a <code>dataset</code> function. This will allow you to create a <code>dataset</code>, which is the object from which you will interact with the Google Cloud Datastore.
         </p>
         <div hljs>
-  var datastore = gcloud.datastore;
-  var dataset = datastore.dataset({
-    projectId: 'myProject',
-    keyFilename: '/path/to/keyfile.json'
-        </div>
-          <p ng-if="!isActiveUrl('/docs/datastore/dataset')">
-            See <a href="#/docs/{{version}}/datastore/dataset">the Dataset documentation</a> for examples of how to query the datastore, save entities, run a transaction, and others.
-          </p>
-        </article>
-
-        <article ng-if="isActiveDoc('storage')">
-          <p>
-            The <code>gcloud.storage</code> object contains a <code>Bucket</code> object, which is how you will interact with your Google Cloud Storage bucket.
-          </p>
-          <div hljs>
-  var storage = gcloud.storage;
-  var bucket = new storage.Bucket({
-    bucketName: 'MyBucket'
-  });</div>
+var datastore = gcloud.datastore;
+var dataset = datastore.dataset({
+  projectId: 'myProject',
+  keyFilename: '/path/to/keyfile.json'
+});</div>
         <p ng-if="!isActiveUrl('/docs/datastore/dataset')">
-          See <a href="#/docs/datastore/dataset">the Dataset documentation</a> for examples of how to query the datastore, save entities, run a transaction, and others.
+          See <a href="#/docs/{{version}}/datastore/dataset">the Dataset documentation</a> for examples of how to query the datastore, save entities, run a transaction, and others.
         </p>
       </article>
+
       <article ng-if="isActiveDoc('storage')">
-        <h2>Overview</h2>
+        <h3>Storage Overview</h3>
         <p>
           The <code>gcloud.storage</code> object contains a <code>bucket</code> object, which is how you will interact with your Google Cloud Storage bucket. See the guide on <a href="https://developers.google.com/storage">Google Cloud Storage</a> to create a bucket.
         </p>
+        <div hljs>
+var bucket = gcloud.storage.bucket({
+  bucketName: 'MyBucket'
+});</div>
         <p>
           See examples below for more on how to access your bucket to upload a file, read its files, create signed URLs, and more.
         </p>
@@ -117,10 +107,12 @@ <h2 ng-if="method.name[0].toUpperCase() === method.name[0]">
         <h4 ng-show="method.params">Parameters</h4>
         <table class="table" ng-show="method.params">
           <tbody>
-            <tr ng-repeat="param in method.params">
+            <tr
+              ng-repeat="param in method.params"
+              ng-class="{ 'param-optional': param.optional }">
               <th scope="row">{{param.name}}</th>
-              <td ng-bind-html="param.types"></td>
-              <td ng-bind-html="param.description"></td>
+              <td class="param-types" ng-bind-html="param.types"></td>
+              <td class="param-description" ng-bind-html="param.description"></td>
             </tr>
           </tbody>
         </table>
@@ -146,14 +138,14 @@ <h4 ng-show="method.example">Example</h4>
     <ul class="page-sections" ng-show="showReference">
       <li ng-repeat="page in pages">
         <a
-          ng-class="{ current: docs.isActiveUrl(page.url) }"
+          ng-class="{ current: isActiveUrl(page.url) }"
           ng-href="{{page.url}}">
           {{page.title}}
         </a>
         <ul class="sub-sections" ng-if="page.pages">
           <li ng-repeat="innerPage in page.pages">
             <a
-              ng-class="{ current: docs.isActiveUrl(page.url + innerPage.url) }"
+              ng-class="{ current: isActiveUrl(page.url + innerPage.url) }"
               ng-href="{{page.url + innerPage.url}}">
               {{innerPage.title}}
             </a>
diff --git a/docs/components/docs/docs.js b/docs/components/docs/docs.js
index fe0f1387a28..568ff7c0409 100644
--- a/docs/components/docs/docs.js
+++ b/docs/components/docs/docs.js
@@ -80,6 +80,7 @@ angular
                       formatHtml(tag.description.replace(/^- /, '')));
                   tag.types = $sce.trustAsHtml(tag.types.reduceRight(
                       reduceModules, []).join(', '));
+                  tag.optional = tag.types.toString().substr(-1) === '=';
                   return tag;
                 }),
               returns: obj.tags.filter(function(tag) {
@@ -197,15 +198,16 @@ angular
         }
       });
   })
+
   .controller('DocsCtrl', function($location, $scope, $routeParams, methods, $http, versions) {
     'use strict';
 
     $scope.isActiveUrl = function(url) {
-      var current = $location.path().replace('/' + methods.singleMethod, '');
-      var link = url
-          .replace(/^#/, '')
-          .replace('/' + methods.singleMethod, '');
-      return current === link;
+      var active = $location.path()
+          .replace('/' + methods.singleMethod, '')
+          .replace('/' + $scope.version, '');
+      url = url.replace('#', '').replace('/' + $scope.version, '');
+      return active === url;
     };
 
     $scope.isActiveDoc = function(doc) {
@@ -252,7 +254,8 @@ angular
       }
     ];
   })
-  .controller("HistoryCtrl", function($scope, versions) {
+
+  .controller('HistoryCtrl', function($scope, versions) {
     $scope.pageTitle = 'Node.js Docs Versions';
     $scope.showHistory = true;
     $scope.versions = versions;
diff --git a/docs/components/docs/history.html b/docs/components/docs/history.html
deleted file mode 100644
index e69de29bb2d..00000000000
diff --git a/docs/css/main.css b/docs/css/main.css
index 12a46ff478e..32a20d55194 100755
--- a/docs/css/main.css
+++ b/docs/css/main.css
@@ -603,6 +603,16 @@ h2, h3 {
     border-bottom: 1px solid rgba(0,0,0,0.05);
 }
 
+.param-optional .param-types {
+  font-style: italic;
+}
+
+.param-optional .param-description:before {
+  content: "optional. ";
+  color: #aaa;
+  font-style: italic;
+}
+
 .method-heading {
     position: relative;
 }
@@ -627,7 +637,7 @@ h2, h3 {
 
 .sub-heading {
   color: #5d6061;
-  margin: 0;
+  margin: 0 !important;
 }
 
 .toggler {