From 78b7c04457354b9f5398e8ce90ef597771dbf212 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Fri, 20 Sep 2019 08:09:51 +1200
Subject: [PATCH] Fix white space in generated API docs

---
 .../hifi-jsdoc-template/static/styles/jsdoc.css   | 13 ++++++++-----
 .../hifi-jsdoc-template/tmpl/description.tmpl     | 15 +++++++++++++++
 tools/jsdoc/hifi-jsdoc-template/tmpl/members.tmpl |  2 +-
 tools/jsdoc/hifi-jsdoc-template/tmpl/method.tmpl  |  8 ++++----
 .../hifi-jsdoc-template/tmpl/methodList.tmpl      |  6 ++----
 tools/jsdoc/hifi-jsdoc-template/tmpl/params.tmpl  | 13 +++++++++----
 .../hifi-jsdoc-template/tmpl/properties.tmpl      |  4 +++-
 tools/jsdoc/hifi-jsdoc-template/tmpl/signal.tmpl  |  8 ++++----
 .../hifi-jsdoc-template/tmpl/signalList.tmpl      |  8 +++-----
 9 files changed, 49 insertions(+), 28 deletions(-)
 create mode 100644 tools/jsdoc/hifi-jsdoc-template/tmpl/description.tmpl

diff --git a/tools/jsdoc/hifi-jsdoc-template/static/styles/jsdoc.css b/tools/jsdoc/hifi-jsdoc-template/static/styles/jsdoc.css
index 2386f88586..7b666de37b 100644
--- a/tools/jsdoc/hifi-jsdoc-template/static/styles/jsdoc.css
+++ b/tools/jsdoc/hifi-jsdoc-template/static/styles/jsdoc.css
@@ -143,6 +143,14 @@ td {
     border: solid #c7cccb 1px;
 }
 
+td > p:first-child, td > ul:first-child {
+    margin-top: 0;
+}
+
+td > p:last-child, td > ul:last-child {
+    margin-bottom: 0;
+}
+
 article table thead tr th, article table tbody tr td, article table tbody tr td p {
     font-size: .89rem;
     line-height: 20px;
@@ -596,11 +604,6 @@ header {
    font-size: 100%;
 }
 
-.params td.description > p:first-child, .props td.description > p:first-child {
-   margin-top: 0;
-   padding-top: 0;
-}
-
 span.param-type, .params td .param-type, .param-type dd {
   color: #606;
   font-family: Consolas, Monaco, 'Andale Mono', monospace
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/description.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/description.tmpl
new file mode 100644
index 0000000000..0e0ad27b37
--- /dev/null
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/description.tmpl
@@ -0,0 +1,15 @@
+<?js
+    var description = obj;
+    var self = this;
+    var descriptionRegExp = new RegExp('<(p|ul|div|table)[^>]*>', 'i');
+    var descriptionIndex =  description.search(descriptionRegExp);
+?>
+
+<?js if (descriptionIndex === -1) { ?>
+    <p><?js= description ?></p>
+<?js } else if (descriptionIndex !== 0) { ?>
+    <p><?js= description.slice(0, descriptionIndex) ?></p>
+    <?js= description.slice(descriptionIndex) ?>
+<?js } else { ?>
+    <?js= description ?>
+<?js } ?>
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/members.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/members.tmpl
index c97a3f6979..6a870b4cda 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/members.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/members.tmpl
@@ -16,7 +16,7 @@ var self = this;
         <tr>
             <td>
                 <?js if (data.description) { ?>
-                    <div><?js= data.description ?></div>
+                    <?js= self.partial('description.tmpl', data.description) ?>
                 <?js } else { ?>
                     <p style="color:red;">&nbsp;</p>
                 <?js } ?>                    
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/method.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/method.tmpl
index db52d8f0b5..1542ca1806 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/method.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/method.tmpl
@@ -25,10 +25,10 @@ var self = this;
             <tr>
                 <td>
                     <?js if (data.kind !== 'module' && !data.hideconstructor) { ?>
-                        <div>
-                            <?js= data.description ?>
-                            <?js= this.partial('details.tmpl', data) ?>
-                        </div>
+                        <?js if (data.description) { ?>
+                            <?js= self.partial('description.tmpl', data.description) ?>
+                        <?js } ?>
+                        <?js= this.partial('details.tmpl', data) ?>
                     <?js } else { ?>
                         <p style="color:red;">&nbsp;</p>
                     <?js } ?>                    
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/methodList.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/methodList.tmpl
index 7d88cd5e51..982c231fd9 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/methodList.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/methodList.tmpl
@@ -29,11 +29,9 @@ var self = this;
                 </td>
                 <td>
                 <?js if (data.description) { ?>
-                <?js= description ?>
-                <?js= this.partial('details.tmpl', data) ?>
-                <?js } else { ?>
-                    <?js= this.partial('details.tmpl', data) ?>
+                    <?js= this.partial('description.tmpl', data.description) ?>
                 <?js } ?>
+                <?js= this.partial('details.tmpl', data) ?>
                 </td>
             </tr>
     <?js } ?>
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/params.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/params.tmpl
index e994e42bfa..dd9f5f7ee7 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/params.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/params.tmpl
@@ -120,10 +120,15 @@
                 </td>
             <?js } ?>
 
-            <td class="description last"><?js= param.description ?><?js if (param.subparams) { ?>
-                <h6>Properties</h6>
-                <?js= self.partial('params.tmpl', param.subparams) ?>
-            <?js } ?></td>
+            <td class="description last">
+                <?js if (param.description) { ?>
+                    <?js= self.partial('description.tmpl', param.description) ?>
+                <?js } ?>
+                <?js if (param.subparams) { ?>
+                    <h6>Properties</h6>
+                    <?js= self.partial('params.tmpl', param.subparams) ?>
+                <?js } ?>
+            </td>
         </tr>
 
     <?js }); ?>
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/properties.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/properties.tmpl
index 5c83a7d587..31717ed63b 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/properties.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/properties.tmpl
@@ -87,7 +87,9 @@
             <?js } ?>
 
             <td class="description last">
-                <?js= prop.description ?>
+                <?js if (prop.description) { ?>
+                    <?js= self.partial('description.tmpl', prop.description) ?>
+                <?js } ?>
                 <?js if (props.hasDefault) {?>
                         <?js if (typeof prop.defaultvalue !== 'undefined') { ?>
                             <p><b>Default Value:</b> <?js= self.htmlsafe(prop.defaultvalue) ?> </p>
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/signal.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/signal.tmpl
index ece03b9e36..76d6f78948 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/signal.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/signal.tmpl
@@ -25,10 +25,10 @@ var self = this;
             <tr>
                 <td>
                     <?js if (data.kind !== 'module' && !data.hideconstructor) { ?>
-                        <div>
-                            <?js= data.description ?>
-                            <?js= this.partial('details.tmpl', data) ?>
-                        </div>
+                        <?js if (data.description) { ?>
+                            <?js= self.partial('description.tmpl', data.description) ?>
+                        <?js } ?>
+                        <?js= this.partial('details.tmpl', data) ?>
                     <?js } else { ?>
                         <p style="color:red;">&nbsp;</p>
                     <?js } ?>                    
diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/signalList.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/signalList.tmpl
index c5fdefc7d8..98b0892122 100644
--- a/tools/jsdoc/hifi-jsdoc-template/tmpl/signalList.tmpl
+++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/signalList.tmpl
@@ -13,12 +13,10 @@ var self = this;
                     <code><?js= (kind === 'class' ? 'new ' : '') + name + (data.signatureHead || '') ?></code></a>
                 </td>
                 <td>
-                <?js if (data.description) { ?>
-                <?js= description ?>
-                <?js= this.partial('details.tmpl', data) ?>
-                <?js } else { ?>
+                    <?js if (data.description) { ?>
+                        <?js= this.partial('description.tmpl', description) ?>
+                    <?js } ?>
                     <?js= this.partial('details.tmpl', data) ?>
-                <?js } ?>
                 </td>
             </tr>
     <?js } ?>