first. wip.

Author: heapwolf

.gitignore

@@ -0,0 +1 @@
+/node_modules

README.md

@@ -0,0 +1,54 @@
+# SYNOPSIS
+A minimal documentation system.
+
+
+# MOTIVATION
+Optimized for being learned, read and maintained. Generate a
+machine readable AST first, docs second.
+
+
+# SYNTAX
+Place tripple forward slashes in front of doc lines. See [this][0]
+example.
+
+```c++
+/// <keyword> ...args
+```
+
+
+# KEYWORDS
+
+#### namespace `name`
+Each header defines only one namespace.
+
+#### class `name`
+Each class is associated with the last namespace.
+
+#### method `name(...args)`
+Each method is associated with the last class.
+
+#### overload `name(...args)`
+An overload is a type of method.
+
+#### function `name(...args)`
+A function is a 
+
+#### return `type`
+Each return is associated with the last function, method or overload.
+
+#### param `name` `text...`
+Each param is associaated with the last function or method.
+
+#### comment `text...`
+Each comment is associated with the last keyword.
+
+
+# PARSER
+Outputs an AST. See [this][1] example.
+
+
+# COMPILER
+Outputs markdown or html.
+
+[0]:/test/fixtures/index.hxx
+[1]:/test/fixtures/tree.json

bin/docs

@@ -0,0 +1,80 @@
+const fs = require('fs')
+const path = require('path')
+
+const parse = require('./parse')
+
+//
+// Find all header files except in ./deps or hidden dirs
+//
+const read = d => {
+  const files = fs.readdirSync(d)
+  let paths = files.map(f => path.join(d, f))
+
+  let headers = []
+
+  for (const i in paths) {
+    const p = paths[i]
+    const base = path.basename(p)
+
+    if (base[0] === '.' || (base === 'deps')) {
+      continue
+    }
+
+    const stat = fs.statSync(p)
+
+    if (stat.isDirectory()) {
+      headers.push(...read(p))
+    } else if (path.extname(p) === '.hxx') {
+      headers.push(p)
+    }
+  }
+
+  return headers
+}
+
+//
+// Find the package.json for any given header file
+//
+const findPackage = file => {
+  const dir = path.dirname(file)
+  const target = path.join(dir, 'package.json')
+
+  try {
+    fs.statSync(target)
+  } catch (ex) {
+    return findPackage(path.join(dir, '..'))
+  }
+
+  return require(target)
+}
+
+const parseUrl = s => {
+  let url = s.split('//')[1]
+  if (!url) url = s.split('@')[1]
+
+  return url.replace(':', '/').replace('.git', '')
+}
+
+//
+// Read all files from a path and parse their headers for docs
+//
+function main (argv) {
+  const files = read(argv[0])
+
+  for (const file of files) {
+    const pkg = findPackage(file)
+
+    if (!pkg) {
+      console.error('missing package.json for', file)
+      continue
+    }
+
+    const s = fs.readFileSync(file, 'utf8')
+    const output = parse(s)
+
+    output.repo = parseUrl(pkg.repository.url)
+    console.log(JSON.stringify(output, 2, 2))
+  }
+}
+
+main(process.argv.slice(2))

compile.js

@@ -0,0 +1,23 @@
+{
+  "name": "hyper-docs",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "bin": "bin/docs",
+  "scripts": {
+    "test": "node test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/datcxx/hyper-docs.git"
+  },
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/datcxx/hyper-docs/issues"
+  },
+  "homepage": "https://github.com/datcxx/hyper-docs#readme",
+  "dependencies": {
+    "marked": "^0.6.2"
+  }
+}

index.js

@@ -0,0 +1,145 @@
+//
+// Parse each line 
+//
+module.exports = source => {
+  const DOC_RE = /\/\/\/(.*)[\n|\r]/g
+
+  let docr = DOC_RE.exec(source)
+  let lines = []
+
+  if (!docr) {
+    return {}
+  }
+
+  while (docr) {
+    if (docr[1]) {
+      lines.push(docr[1].trim())
+    }
+
+    docr = DOC_RE.exec(source)
+  }
+
+  const output = {
+    namespace: [],
+    classes: {},
+    functions: [],
+  }
+
+  let lastClass = null
+  let lastMethod = null
+  let hasConstructor = false
+  let last = null
+
+  //
+  // Parses all lines of the file, the rule for docs is
+  // last-one-in-wins like css.
+  //
+  const parseLine = line => {
+    const words = line.split(' ')
+    const keyword = words.shift()
+
+    switch (keyword) {
+      case 'namespace': {
+        output.namespace.push(words[0])
+        break
+      }
+
+      case 'comment': {
+        if (!last.comment) {
+          last.comment = ''
+        }
+        last.comment += ' ' + words.join(' ')
+        last.comment = last.comment.trim()
+        break
+      }
+
+      case 'class': {
+        lastClass = words.shift()
+        last = output.classes[lastClass] = []
+        break
+      }
+
+      case 'operator': {
+        last = {
+          operator: words.join(' ')
+        }
+        output.classes[lastClass].push(last)
+        break
+      }
+
+      case 'return': {
+        const type = words[0]
+
+        last = {
+          type,
+          reference: type.includes('&'),
+          pointer: type.includes('*')
+        }
+
+        lastMethod['return'] = last
+        break
+      }
+
+      case 'param': {
+        const identifier = words.shift()
+
+        if (!last.params[identifier]) {
+          console.error(`Unknown parameter ${identifier}`)
+          process.exit(1)
+        }
+
+        last.params[identifier].comment += words.join(' ')
+        break
+      }
+
+      case 'property': {
+        last = {
+          property: words.join(' ')
+        }
+
+        output.classes[lastClass].push(last)
+        break
+      }
+
+      case 'overload':
+      case 'constructor':
+      case 'method': {
+        let params = {}
+
+        line = line.replace(/\((.*)\)/, (_, sig) => {
+          sig.split(',').filter(Boolean).forEach(param => {
+            params[param.match(/\w+$/)] = {
+              const: !!param.match(/\s+const|const\s+/),
+              reference: !!param.match(/&/),
+              pointer: !!param.match(/\*/),
+              comment: ''
+            }
+          })
+          return ''
+        })
+
+        last = lastMethod = {
+          name: line.split(' ').pop(),
+          type: 'method',
+          overload: keyword === 'overload',
+          params
+        }
+
+        if (keyword === 'constructor' && hasConstructor) {
+          lastMethod.overload = true
+        }
+
+        if (keyword === 'constructor') {
+          hasConstructor = true
+        }
+
+        output.classes[lastClass].push(lastMethod)
+
+        break
+      }
+    }
+  }
+
+  lines.forEach(parseLine)
+  return output
+}