Closed cdtweb closed 10 years ago
I personally prefeer not use api doc in the same files of code. I have other project only for documentation and I have js files with only commented code for API Doc.
I did find that using @apiStop
or any other annotation that isn't defined and being parsed will actually achieve what I'm looking for.
I personally create 2 blocks (easier to read too)
/**
* @api {get} /example Get example
* @apiName GetExample
* @apiVersion 0.0.1
* @apiExample Example Usage
* GET /example
*/
/**
* Handle GET request
* @return boolean
*/
In a future release i remove the fixed doc blocks /**...*/
, so that it is possible, that the @api-Params can be used over many lines (inline the code, not only in a block outside)
e.g.
/**
* @api {get} /example Get example
* @apiName GetExample
* @apiVersion 0.0.1
*/
function foo(req)
{
// @apiParam {String} param1 The first parameter.
var param1 = req.param1 || 'default';
}
To follow up on my previous comment:
I had written a shell script that send all output to /dev/null so I didn't see that having @apiStop (which is not supported or defined) is actually throwing an error during the generation process.
apidoc: parser plugin "apistop" not found.
This does not stop apidoc from parsing all of the remaining docblocks so I didn't notice this issue until later on.
@rottman I think that being able to define @api-Params like that would be great.
Feel free to close this issue if you feel it to be unnecessary.
Thanks!
@CodersBrothers could you please contact me amr@venatra.com
When adding @api annotations to inline comment block (for a class method, for example) it would be nice to be able to define start and end points for the generator so that I can keep my native comments separated from the @api docs without having to put them into a different block.. For example: