dox-template not outputting documentation?

[dgendill]

Hey, how's it going. I just started using Node, dox, and your dox-template program. I'm running dox on this javascript file:

https://github.com/dgendill/Javascript-Interpreter/blob/master/compiler.js

and I'm getting the following json object...

[ { tags:
     [ { type: 'param',
         types: [ 'Object' ],
         name: 'musexpr',
         description: 'An object structured in the MUS Language.\r' },
       { type: 'return',
         types: [ 'Object' ],
         description: 'Returns an object sructured in the NOTE Language.' } ],
    description:
     { full: '<p>Compiles the made up music language MUS into the madeup music l
anguage NOTE.</p>',
       summary: '<p>Compiles the made up music language MUS into the madeup musi
c language NOTE.</p>',
       body: '' },
    isPrivate: false,
    ignore: false,
    code: 'var compile = function (musexpr) {\r\n    var time = 0;\r\n    var no
tes = [];\r\n    var duration = 0;\r\n    \r\n    var section = function(expr, i
ncrement) {\r\n\t\tif (expr.tag === \'seq\') {\r\n\t\t\tsection(expr.left, true)
;\r\n\t\t\tsection(expr.right, true);\r\n\t\t} else if (expr.tag === \'par\') {\
r\n\t\t\tsection(expr.left, false);\r\n\t\t\tsection(expr.right, true);\r\n\t\t}
 else {\t\t\t\r\n\t\t\tvar toReturn = {\r\n\t\t\t\ttag:expr.tag,\r\n\t\t\t\tpitc
h:expr.pitch,\r\n\t\t\t\tstart:time,\r\n\t\t\t\tdur:expr.dur\r\n\t\t\t};\r\n\t\t
\t//duration = (expr.dur > duration) ? expr.dur : duration;\r\n\t\t\tif (increme
nt) {\r\n\t\t\t\ttime = time + expr.dur;\r\n\t\t\t\t//duration = 0;\t\t\t\t\r\n\
t\t\t}\r\n\t\t\tnotes.push(toReturn);\r\n\t\t}\r\n    };\r\n    section(musexpr)
;\r\n    return notes;\r\n};',
    ctx:
     { type: 'function',
       name: 'compile',
       string: 'compile()' } } ]

When I run dox < compile.js | dox-template -r 0.0.1 > readme.html I get the readme.html file, but the template file is empty. All it says is "Davis.js" with a search bar next to it. Any ideas what's going on?

[olivernn]

Hi,

Dox template was extracted from the doc tools for davis.js, I must've left 'Davis.js' in the template file by mistake!

The reason that you aren't seeing anything in the html is because dox template is fairly opinionated about the input it is expecting. It expects your code to be grouped into modules, which are defined with a custom tag of @module. An example, from Davis.js, is https://github.com/olivernn/davis.js/blob/master/lib/davis.logger.js. This is a module that is similar to your example in that it is really just a function.

I'll get round to removing 'Davis.js' from the template too.

[dgendill]

Ok, cool. Yeah, looks like that solved my problem. I had to create a wrapper function and define that as my module. I also had to change my document formatting from tabs to spaces - for some reason that was interfering with either dox or dox-template.

Thanks for your help!

[olivernn]

Sorry this has taken so long, it completely slipped my mind!

I've pushed a change so that you can specify the name of the library rather than it defaulting to Davis.js, you have to pass in a name option when building your docs, e.g.

dox-template -n "Awesome Lib!"

I've pushed the code but npm is having some issues currently so can't publish the new version, I'll keep trying though so v0.1.1 will have the fix.

[kmiklas]

dox template is fairly opinionated about the input it is expecting"

Any documentation available regarding dox template expectations for input?

tyvm

[olivernn]

It should just be the output that comes from dox itself, if that isn't working then it is a bug in this lib, please open an issue.

If you are trying to use this without dox then there currently isn't any documentation (ironic for a documentation tool) but you might find looking at what dox itself outputs a good start.