From c0fb8297a665aaea7a53081f64a00a78d34caf59 Mon Sep 17 00:00:00 2001
From: Mike Gerwitz <mtg@gnu.org>
Date: Mon, 21 Aug 2017 02:39:09 -0400
Subject: [PATCH] Prebirth: Add docstring

* build-aux/bootstrap/prebirth.js (Compiler#_docstring): Add method.
  (Compiler#_cdfn): Use it.
---
 build-aux/bootstrap/prebirth.js | 37 ++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/build-aux/bootstrap/prebirth.js b/build-aux/bootstrap/prebirth.js
index b648cb6..b1cb739 100644
--- a/build-aux/bootstrap/prebirth.js
+++ b/build-aux/bootstrap/prebirth.js
@@ -321,15 +321,45 @@ class Compiler
     {
         this.assertApply( t, 'define-block' );
 
-        // e.g. (define-block <foo> ((input ...)) body)
-        const [ , { value: name }, desc, ...body ] = t;
+        // e.g. (define-block <foo> doc ((input ...)) body)
+        const [ , { value: name }, doc, desc, ...body ] = t;
 
         const id     = this._idFromName( name );
+        const docstr = this._docstring( doc );
         const bodyjs = this._bodyToEs( body );
 
         // this is the final format---each block becomes its own function
         // definition
-        return `function ${id}()\n{\n${bodyjs}\n};`;
+        return `${docstr}\nfunction ${id}()\n{\n${bodyjs}\n};`;
+    }
+
+
+    /**
+     * Compile docblock string
+     *
+     * This converts to the docstring T into a docblock.  No annotations are
+     * generated---it is output verbatim.  If the docstring is the empty
+     * string, then the empty string is returned.
+     *
+     * @param {string} t docstring token
+     *
+     * @return {string} generated docblock or the empty string
+     */
+    _docstring( t )
+    {
+        if ( t.type !== 'string' ) {
+           throw TypeError( `Expected string docblock, but found ${t.type}` );
+        }
+
+        const doc = t.value;
+
+        // don't bother with the docblock generation if we have nothing useful
+        if ( !doc ) {
+           return "";
+        }
+
+        // enclose in multi-line comment delimiters and prefix each line
+        return "/**\n" + doc.replace( /^/g, " * " ) + "\n */";
     }
 
 
@@ -525,6 +555,7 @@ class Compiler
  * Here is an example Hello, World!:
  *
  *   (define-block <hello-world>
+ *     "A simple 'Hello, World!' program."
  *     ()
  *     (<js:console> ((message "Hello, world!"))))
  *