Documenting Complex Project

[Queuecumber]

I have a complex project with several modules and many js files in a directory structure. With JSDoc I could point to the root of my source code and it would traverse the directory structure recursively and generate documentation for every file.

I have since added a large C++ portion to my project as a node addon so I wanted to document it as well and it seems that documentationjs supports that. However I can't get it to generate documentation in the same way. Is there a standard way to traverse a large project like this?

[tmcw]

Right now there are two modes for documentationjs:

• Polyglot mode, which takes lists of filenames as input and parses files agnostically
• JavaScript mode, which takes files as input, crawls their dependencies, and parses them as JavaScript

to document cross-language repositories, we would need to separate the input step from the parsing step and have the parser decide on JavaScript vs C++ based on extension or some other cue.

[elwayman02]

@tmcw is it possible to simply provide a directory and have documentationjs parse all files in that directory?

[tmcw]

@elwayman02 sure, you can do

documentation --polyglot directory/*

As previously discussed, though, this uses the polyglot parser that does not do any code inference - to infer JS and polyglot-parse other types, we might need some sort of filename sniffing.

[elwayman02]

@tmcw I get this error when I try that:

$ documentation -f html -o docs --polyglot addon/*
fs.js:552
  var r = binding.read(fd, buffer, offset, length, position);
                  ^
Error: EISDIR, illegal operation on a directory
    at Error (native)
    at Object.fs.readSync (fs.js:552:19)
    at Object.fs.readFileSync (fs.js:384:28)
    at /usr/local/lib/node_modules/documentation/lib/input/shallow.js:26:20
    at Array.map (native)
    at module.exports (/usr/local/lib/node_modules/documentation/lib/input/shallow.js:23:33)
    at module.exports (/usr/local/lib/node_modules/documentation/index.js:80:10)
    at Object.<anonymous> (/usr/local/lib/node_modules/documentation/bin/documentation.js:19:1)
    at Module._compile (module.js:460:26)

[tmcw]

There's probably a directory in that directory and documentation's trying to read it. We do not currently recurse down directories.

[elwayman02]

Ah, yea there definitely is. That's what I'm ultimately looking for; I'd like to take a complex project and input the parent directory, getting back generated documentation for all the files

[tmcw]

Going to rename this module to reflect the idea that maybe normal mode and polyglot mode shouldn't be mutually exclusive. For the immediate issue - this illegal operation thing:

• For now, use recursive globs: documentation --polyglot directory/**