Issues getting amd-doc to run

[israels]

I have tried unsuccessfully to get the amddoc.compile() function to execute properly, as is shown in the readme. My generate-amddoc-node file looks exactly like the usage example, except for the config changes detailed below.

Here is the output I get when running via node:

C:\Source>node generate-amddoc-node.js
function bold() { [native code] }
===========================================================

Running jsdoc on 135 files (0 cached)...
undefined564131ms

Updating jsdoc caches for future runs...

C:\source\node_modules\grunt\lib\grunt\file.js:123
        throw grunt.task.taskError('Unable to create directory "' + subpath +
                         ^
Error
    at C:\source\node_modules\grunt\lib\util\task.js:47:25
    at Object.<anonymous> (C:\source\node_modules\grunt\lib\util\task.js:390:2)
    at Module._compile (module.js:449:26)
    at Object.Module._extensions..js (module.js:467:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Module.require (module.js:362:17)
    at require (module.js:378:17)
    at Object.<anonymous> (C:\source\node_modules\grunt\lib\grunt\utils.js:17:14)
    at Module._compile (module.js:449:26)

There are several issues:

1. amd-doc has grunt dependencies. If I run it just through node I get unexpected logged output
2. Run time is almost 10 minutes. For 135 small files this seems extrememly long. Running directly via jsdoc to generate documentation takes under 10 seconds
3. The program terminates prematurely. It creates a cache.json file (after 10 minutes), but does not produce any other output

The only config I have modified from the readme are the following values:

//files to process for documentation
include: '../src/js/**/*.js',

//directory to output generated HTML (default = 'doc/out')
out: '../staging/doc/amddoc/out',

//directory to store jsdoc cache (default = 'doc/cache')
cache: '../staging/doc/amddoc/cache',

//Commented Out
//github URL where source is available. the file path and line number of
//each documented variable will be added to this to make source links.
// repoview: 'https://github.com/zship/deferreds.js/blob/develop/',

//requirejs configuration object
//more: https://github.com/jrburke/r.js/blob/master/build/example.build.js
//amd-doc uses `basePath`, `paths`, and `packages` (all optional) to
//transform file names to AMD module names.
requirejs: {
    baseUrl: '../src/js',
    optimize: 'none',
    packages: [
    {  }
    ],
}

Note: I am using Node v0.8.9. Also, I couldn't install your package directly because the git protocol is blocked at my organization. I instead installed it manually using jsdoc 3.1.0. Not sure if that version has anything to do with it.

[zship]

Hi, @israels. Thanks for reporting this. It looks like I did not push the latest code to npm recently, so could you try re-installing amd-doc first? I've just bumped it to 0.1.1 and published.

[israels]

I have reinstalled using latest source from github.

I'm actually getting smaller progress than before. Now it just fails with:
`Fatal error: Cannot call method 'indexOf' of undefined``

[zship]

Hmm... what's different on your machine... could I get the full output of that Fatal error: Cannot call method 'indexOf' of undefined?

[israels]

After investigating, it looks like it was blowing up because opts.files was undefined.
I did not notice your API change of include -> files. I will see if I am successful using the correct object param.

[israels]

I made some progress in execution using the non-grunt version (just calling amddoc.compile).

It starts processing like so (running jsdoc for about 10 minutes):

Generating documentation for 140 files
=========================================================== 

Then it unexpectedly dies with an error

Fatal error: Unexpected token u

There's no other logged info, even when running with verbose option. I tried to debug and it looks like it's failing on parsing the JSDoc stdout output into JSON. The stdout is very large. I will keep looking to see if I can narrow it down any further.

[zship]

Yes, I think you're right about the failure taking place on JSON.parse . If you've read the file runJsdoc.js, you've seen that I'm doing something rather hacky there. To translate between jsdoc which runs in a Rhino environment and amd-doc which runs in Node, I'm asking jsdoc for JSON output and then parsing that on my side. Some of jsdoc's JSON is invalid, though, so I'm passing it through a few regexs before trying to parse. It looks like you ran into a case that I haven't.

It seems the thing to do would be to write stdout to a file (on line 20 or so of runJsdoc.js), then run that through a json linter to see what's invalid. Then we could add that case to the list of regexs (line 22) to filter out.

This is a bit inelegant and I'd like to re-evaluate it at some point. The 10-minute jsdoc running time is also problematic and will be the next thing I tackle on this project.

Would you be able to e-mail me your source? I'd be happy to help you debug this and I'd be interested in seeing what sort of jsdoc comments I'm not handling correctly.

[israels]

It turns out the JSON parse was blowing up because I had example documentation code inline. Your regex was trying to replace an undefined within my example, which added an extra set of quotes. By tweaking this, I was able to get the compile function to finish at least.

Now that I have html files generated, I'm not sure what I am supposed to see. Is there supposed to be any styling applied? Right now, all I see is unstyled html that just has Properties and Methods listed. There is no documentation comments showing up. I was expecting something more like your documentation project here:
http://zship.github.com/deferreds.js/

[zship]

That's good to know, thanks!

I don't style anything by default here. amd-doc is supposed to give bare-bones output, but my projects which use it are using this template: https://github.com/zship/amd-doc-browser . I do need to document this better! (You can tell it's a young project.) You'll probably need a web server to point to the "app" directory in that project, since it uses AJAX requests to load the amd-doc output. You could use the grunt server task if you don't want to configure a web server. Let me know if you encounter any issues getting amd-doc-browser working.

[israels]

The performance issue appears to be a bug within jsdoc when running with the -x option:
jsdoc/jsdoc#298

My project is parsing 140 files, which runs really fast with the normal jsdoc option, but takes 10 minutes using the -x option.