add support for @requires and @member

[lemori]

1. Uses outer jsdoc module rather than embeded one.
2. Enhances output(currently one file each), adds requires and members fields.

Reference: jsdoc documents

USAGE

    /**
       module_description
       @module module_name
       @requires req_1
       @requires req_2
    */
    /** @member */
    var MODULE_MEMBER_1 = [1,2,3];
    /** @member */
    var MODULE_MEMBER_2 = 'abc';

    ...

Will be parsed as:

   module_name
   ===

   module_description

   **Requires:**

   + module:req_1
   + module:req_2

   **Members:**

   + MODULE_MEMBER_1
   + MODULE_MEMBER_2

   ...

[mrjoelkemp]

Hey @lemori, thanks for contributing!

i am not really following the removal of jsdoc3-parser and the use of the outer jsdoc module. Is there a particular use case that prompted this move?

[psq]

funny, I was just looking at it too. I don't think requiring people to install jsdoc3-parser to use jsdox is desirable. If there's a use case for using a more recent version, or a custom version, then make it an option so people can use the global one, or the one at a specific path.

And what are the enhancements? Can you provide some details?

[mrjoelkemp]

@psq Unless I'm misunderstanding, it sounds like a request for accepting piped input into the jsdox binary. Where you could do:

jsdoc -X myfile | jsdox

Additionally, we should support:

jsdox myfile.js --parser=/path/to/my/parser

And if parser is not supplied, then what should we default to?

To avoid hijacking this PR, we should consider moving this discussion into a separate issue if you'd like.

[psq]

@mrjoelkemp both use cases you outline above make sense, and if we can't easily detect there is an input, we can add a command line option (for the first use case). But if there is no parsed input, or a parser provided, I'd use the internal one.

A separate PR would work better indeed.

[lemori]

@mrjoelkemp Hello! jsdox is great, but it failed to run again on my win7, and I can't find out why it crashed(the error message was useless for me). So...it is hijacking:(

--parser option is a good alternative, I should try that.

Probably I had misused the function of fork? I'll revert the codes. Thanks for your advice:)

[lemori]

@psq I added requires and members into the output, like this:

requires:

• module:q

members:

• member: settings

It's only for one doc each time, and it may be buggy.

It's only for testing right now and not ready to merge.

[lemori]

Somehow, jsdox works fine today. I've reverted some codes and can focus on layout now.

UPDATE: It supports directory parsing.

[psq]

@mrjoelkemp looks like we need that way to customize the templates rather sooner than later.

[mrjoelkemp]

Hey @lemori. Thanks again for your work. You've given us the motivation to tackle a few important features:

1. Allowing a custom parser to be supplied: Allow for the --parser option #39
2. Allowing an AST to be supplied via stdin: Support piped input via stdin #40
3. Allowing a user to specify a template directory for custom styling: Allow for the --templateDir option #38

The only aspect of this PR that is mergeable is the addition of requires and members. If you'd like to remove the modifications to function.mustache and squash your commits, then we'll gladly consider merging.

Thanks again for your hard work. Also, feel free to tackle any of the aforementioned issues; we'd love the help in making JSDox more configurable.

[psq]

@mrjoelkemp +1

[lemori]

@mrjoelkemp It's no bad to make a contribution!

I modifies function.mustache to make it cleaner. But I may keep it out of the PR due to #38

Great features to come and I'll try to realize #38

[lemori]

@mrjoelkemp I realized #38 in new PR(#41), you could merge the later if it's OK.

[psq]

I've renamed the pull request to better describe what the latest code is doing now.

But I could not get requires to show up in the output, so do you think you could add a new file in the fixtures directory to demonstrate usage of the 2 new tags?

[lemori]

I don't know how to create a fixture file, though there are some samples.
However, I've updated the very first comment. May it help:)

[psq]

It is easy. Add a file here: https://github.com/sutoiku/jsdox/tree/master/fixtures, and commit the result output here https://github.com/sutoiku/jsdox/tree/master/sample_output

with

node jsdox.js -o sample_output  fixtures/*

[lemori]

Added fixture fixtures/test5.js and sample output sample_output/test5.md

[psq]

yes, something like that. I'll double check as soon as practical, but it looks like I should be able to merge that in. Will let you know.

[psq]

@lemori now that @mrjoelkemp added travis support, would you mind doing a dummy push (like adding a space or empty line) so we can check the tests with travis (assuming you merge again with master, that is)

[lemori]

@psq done.

[mrjoelkemp]

@lemori You have a jshint error that's failing the build:

jsdox.js: line 211, col 19, Expected '{' and instead saw 'return'.

Single line if statements should have the body wrapped in curly braces:

if (foo) { return; }

[lemori]

@mrjoelkemp I was wondering that. It's OK now.