Allow to pick embedded docs from an other comment block than just the…

… first

tools/docgenerator.js

@@ -65,17 +65,29 @@ const IGNORE_WARNINGS = {
  */
 function generateDoc (name, code) {
   // get block comment from code
-  const match = /\/\*\*([^*]|[\r\n]|(\*+([^*/]|[\r\n])))*\*+\//.exec(code)
+  const commentRegex = /\/\*\*([^*]|[\r\n]|(\*+([^*/]|[\r\n])))*\*+\//g
+  // const match = commentRegex.exec(code)
 
-  if (!match) {
+  const comments = findAll(code, commentRegex).map(match => getCommentContents(match[0]))
+
+  // Find the right comment.
+  // First search a comment containing the text "Syntax:" and "Examples:".
+  // If not found, select the first comment
+  const comment = comments.find(comment => {
+    return /\n *syntax: *\n/i.exec(comment) && /\n *examples: *\n/i.exec(comment)
+  }) || comments[0]
+
+  if (!comment) {
     return null
   }
 
   // get text content inside block comment
-  const comment = match[0].replace('/**', '')
-    .replace('*/', '')
-    .replace(/\n\s*\* ?/g, '\n')
-    .replace(/\r/g, '')
+  function getCommentContents (comment) {
+    return comment.replace('/**', '')
+      .replace('*/', '')
+      .replace(/\n\s*\* ?/g, '\n')
+      .replace(/\r/g, '')
+  }
 
   const lines = comment.split('\n')
   let line = ''
@@ -634,6 +646,20 @@ function iteratePath (functionNames, inputPath, outputPath, outputRoot) {
   })
 }
 
+function findAll(text, regex) {
+  const matches = []
+  let match
+
+  do {
+    match = regex.exec(text)
+    if (match) {
+      matches.push(match)
+    }
+  } while (match)
+
+  return matches
+}
+
 // exports
 exports.cleanup = cleanup
 exports.iteratePath = iteratePath