From 10aa3053ebd626001e1d015d2a5961ed8ab90420 Mon Sep 17 00:00:00 2001
From: Eric Goller <elbenfreund@DenkenInEchtzeit.net>
Date: Mon, 9 Apr 2018 15:25:46 +0200
Subject: [PATCH] Add 'stuff' module jsdoc to sphinx

This commit adds the autogenerated jsdoc output to our sphinx
documentation. Its main purpose is to serve as a proof of concept for
the new jsdoc-sphinx setup.
As part of this, the jsdoc markup within ``stuff.js`` had to be fixed as
the previous version was invalid.

Ref.: #257
---
 docs/index.rst       |  1 +
 docs/jsdoc/index.rst |  8 ++++++++
 docs/jsdoc/stuff.rst |  6 ++++++
 extension/stuff.js   | 14 +++++++-------
 4 files changed, 22 insertions(+), 7 deletions(-)
 create mode 100644 docs/jsdoc/index.rst
 create mode 100644 docs/jsdoc/stuff.rst

diff --git a/docs/index.rst b/docs/index.rst
index 0d0e386d..d3842f2f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,3 +24,4 @@ or feel that topics are not covered properly.
    packaging
    versioning
    styleguide
+   jsdoc/index
diff --git a/docs/jsdoc/index.rst b/docs/jsdoc/index.rst
new file mode 100644
index 00000000..0166555e
--- /dev/null
+++ b/docs/jsdoc/index.rst
@@ -0,0 +1,8 @@
+Index of Autodocumented (JSDoc) code
+=====================================
+
+
+.. toctree::
+
+    extension
+    Stuff
diff --git a/docs/jsdoc/stuff.rst b/docs/jsdoc/stuff.rst
new file mode 100644
index 00000000..1a1bbc38
--- /dev/null
+++ b/docs/jsdoc/stuff.rst
@@ -0,0 +1,6 @@
+Stuff.js
+========
+
+.. autofunction:: formatDuration
+.. autofunction:: formatDurationHuman
+.. autofunction:: formatDurationHours
diff --git a/extension/stuff.js b/extension/stuff.js
index 56c70545..d403cb6d 100644
--- a/extension/stuff.js
+++ b/extension/stuff.js
@@ -23,10 +23,10 @@ Copyright (c) 2016 - 2018 Eric Goller / projecthamster <elbenfreund@projecthamst
 
 // Time formatting helpers
 
-/* @function formatDuration
- *
+/**
  * Return time-information formatted as '%HH:%MM'
  *
+ * @function
  * @param {int} - Total amount of seconds to represent.
  */
 function formatDuration(total_seconds) {
@@ -38,11 +38,11 @@ function formatDuration(total_seconds) {
     // This string formatting is not part of JS canon but provided by the shell environment.
     return "%02d:%02d".format(hours, minutes);
 }
-
-/* @function formatDurationHuman
- *
+/**
  * Return time-information as '%HHh %SSmin' or '%SSmin' (if hours=0).
  *
+ * @function
+ *
  * @param {int} - Total amount of seconds to represent.
  */
 function formatDurationHuman(total_seconds) {
@@ -68,11 +68,11 @@ function formatDurationHuman(total_seconds) {
     return result;
 }
 
-/* @function formatDurationHours
- *
+/**
  * Return time-information as decimal (with one decimal place) amount of hours.
  * Example: 'X.Yh'
  *
+ * @function
  * @param {int} - Total amount of seconds to represent.
  */
 function formatDurationHours(seconds) {