From a15eaee78ab186c3b13a79b92b5daaa79cfb7c31 Mon Sep 17 00:00:00 2001
From: Andy Joslin <andytjoslin@gmail.com>
Date: Sat, 8 Mar 2014 20:44:57 -0700
Subject: [PATCH] chore(docs): make service documentation look good

---
 docs/templates/api/api.template.html       |  4 ++
 docs/templates/api/directive.template.html |  7 ++--
 docs/templates/api/object.template.html    |  9 ++++-
 docs/templates/base.template.html          |  2 +-
 docs/templates/lib/macros.html             | 47 +++++++++++++++++-----
 docs/templates/lib/methods.template.html   | 40 +++++++++---------
 docs/templates/pages-data.template.html    |  6 ++-
 7 files changed, 78 insertions(+), 37 deletions(-)

diff --git a/docs/templates/api/api.template.html b/docs/templates/api/api.template.html
index 5febfc4e7f..ff0f233550 100644
--- a/docs/templates/api/api.template.html
+++ b/docs/templates/api/api.template.html
@@ -3,7 +3,11 @@
 <@ block content @>
 
 <@ block header @>
+  <@ if doc.docType == "directive" @>
 ## <$ doc.name | dashCase $>
+  <@ else @>
+## <$ doc.name $>
+  <@ endif @>
 <@ endblock @>
 
 <@ block description @>
diff --git a/docs/templates/api/directive.template.html b/docs/templates/api/directive.template.html
index 8967a9ec8a..4f7eacaf0c 100644
--- a/docs/templates/api/directive.template.html
+++ b/docs/templates/api/directive.template.html
@@ -6,9 +6,7 @@
   <@ block usage @>
 ## Usage
   <@ if doc.usage @>
-
 <$ doc.usage $>
-
   <@ else @>
     <@ if doc.restrict.element @>
 
@@ -48,6 +46,9 @@
   <@- endif @>
   <@ endblock -@>
 
-  <@ include "lib/params.template.html" @>
+  <@ if doc.params @>
+## API
+<$ paramTable(doc.params, true) $>
+  <@ endif @>
   <@ include "lib/events.template.html" @>
 <@ endblock @>
diff --git a/docs/templates/api/object.template.html b/docs/templates/api/object.template.html
index c6a937e7c2..bf8723a9fe 100644
--- a/docs/templates/api/object.template.html
+++ b/docs/templates/api/object.template.html
@@ -1,12 +1,17 @@
 <@ include "lib/macros.html" @>
 <@ extends "api/api.template.html" @>
 
-<@ block additional @>  
+<@ block additional @>
+
+<@ if doc.usage @>
+## Usage
+<$ doc.usage $>
+<@ endif @>
 
   <@ if doc.params or doc.returns or doc.this or doc.kind == 'function' -@>
     <h2 id="usage">Usage</h2>
     <@ if doc.usage @>
-      <$ doc.usage | code $>
+      <$ doc.usage $>
     <@ else @>
       <$ functionSyntax(doc) $>
     <@ endif @>
diff --git a/docs/templates/base.template.html b/docs/templates/base.template.html
index 891d2e5aa6..6ec8128ac9 100644
--- a/docs/templates/base.template.html
+++ b/docs/templates/base.template.html
@@ -1,7 +1,7 @@
 ---
 layout: docs_0.9.0
 active: javascript
-title: "<$ doc.name | dashCase $>"
+title: "<@ if doc.docType == "directive" @><$ doc.name | dashCase $><@ else @><$ doc.name $><@ endif @>"
 header_sub_title: "<$ doc.docType | capital $> in module <$ doc.module $>"
 doc: "<$ doc.name $>"
 ---
diff --git a/docs/templates/lib/macros.html b/docs/templates/lib/macros.html
index ba18034176..9e893330bc 100644
--- a/docs/templates/lib/macros.html
+++ b/docs/templates/lib/macros.html
@@ -2,6 +2,37 @@
 <@ for typeName in types @><a href="" class="<$ typeName | typeClass $>"><$ typeName | escape $></a><@ endfor @>
 <@- endmacro -@>
 
+<@ macro paramTable(params, isDirective) @>
+<table class="table">
+  <thead>
+    <tr>
+      <th><@ if isDirective @>Attr<@ else @>Param<@ endif @></th>
+      <th>Type</th>
+      <th>Details</th>
+    </tr>
+  </thead>
+  <tbody>
+    <@ for param in params @>
+    <tr>
+      <td>
+        <$ param.name $>
+        <@ if param.alias @>| <$ param.alias $><@ endif @>
+        <@ if param.type.optional @><div><em>(optional)</em></div><@ endif @>
+      </td>
+      <td>
+        <$ param.type.name $>
+      </td>
+      <td>
+        <$ param.description | marked $>
+        <@ if param.default @><p><em>(default: <$ param.default $>)</em></p><@ endif @>
+      </td>
+    </tr>
+    <@ endfor @>
+  </tbody>
+</table>
+<@ endmacro @>
+
+
 <@- macro directiveParam(name, type, join, sep) @>
   <@- if type.optional @>[<@ endif -@>
   <$ name | dashCase $><$ join $><$ type.description $><$ sep $>
@@ -9,21 +40,19 @@
 <@ endmacro -@>
 
 <@- macro functionSyntax(fn) @>
-  <@- set sep = joiner(', ') -@>
-  <@ marked -@>
-    `<$ fn.name $>(<@- for param in fn.params @><$ sep() $>
-    <@- if param.type.optional @>[<@ endif -@>
-    <$ param.name $>
-    <@- if param.type.optional @>]<@ endif -@>
-    <@ endfor @>);`
-  <@- endmarked @>
+<@- set sep = joiner(', ') -@>
+`<$ fn.name $>(<@- for param in fn.params @><$ sep() $>
+<@- if param.type.optional @>[<@ endif -@>
+<$ param.name $>
+<@- if param.type.optional @>]<@ endif -@>
+<@ endfor @>)`
 <@ endmacro -@>
 
 <@- macro typeInfo(fn) -@>
 <table class="variables-matrix return-arguments">
   <tr>
     <td><$ typeList(fn.typeList) $></td>
-    <td><$ fn.description | marked $></td>
+    <td><$ fn.description $></td>
   </tr>
 </table>
 <@- endmacro -@>
diff --git a/docs/templates/lib/methods.template.html b/docs/templates/lib/methods.template.html
index 81b60132f5..a7d63e81ab 100644
--- a/docs/templates/lib/methods.template.html
+++ b/docs/templates/lib/methods.template.html
@@ -1,27 +1,25 @@
 <@- if doc.methods @>
-<h2>Methods</h2>
-<ul class="methods">
-  <@- for method in doc.methods @>
-  <li id="<$ method.name $>">
-    <h3><$ functionSyntax(method) $></h3>
-    <div><$ method.description | marked $></div>
+## Methods
+<@- for method in doc.methods @>
 
-    <@ if method.params @>
-    <h4>Parameters</h4>
-    <$ paramTable(method.params) $>
-    <@ endif @>
+<div id="<$ method.name $>"></div>
+### <$ functionSyntax(method) $>
 
-    <@ if method.this @>
-    <h4>Method's <@ code @>this<@ endcode @></h4>
-    <$ method.this | marked $>
-    <@ endif @>
+<$ method.description $>
+
+<@ if method.params @>
+<$ paramTable(method.params) $>
+<@ endif @>
+
+<@ if method.this @>
+#### Method's `this`
+<$ method.this $>
+<@ endif @>
     
-    <@ if method.returns @>
-    <h4>Returns</h4>
-    <$ typeInfo(method.returns) $>
-    <@ endif @>
+<@ if method.returns @>
+**** Returns
+<$ typeInfo(method.returns) $>
+<@ endif @>
 
-  </li>
-  <@ endfor -@>
-</ul>
+<@ endfor -@>
 <@- endif -@>
diff --git a/docs/templates/pages-data.template.html b/docs/templates/pages-data.template.html
index 397c165ff7..316045b5e5 100644
--- a/docs/templates/pages-data.template.html
+++ b/docs/templates/pages-data.template.html
@@ -148,7 +148,11 @@
                 <@ else @>
                   <li class="menu-item{% if page.doc == "<$ navItem.name $>" %} active{% endif %}">
                     <a href="{{ site.docs_0_9_0 }}/angularjs/<$ navItem.href $>">
-                      <$ navItem.name | dashCase $>
+                      <@ if navItem.type == "directive" @>
+                        <$ navItem.name | dashCase $>
+                      <@ else @>
+                        <$ navItem.name $>
+                      <@ endif @>
                     </a>
                   </li>
                 <@ endif @>