Request: Inline docblock @apiStart and/or @apiStop

[cdtweb]

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:

<?php
class Example
{
    /**
     * @api {get} /example Get example
     * @apiName GetExample
     * @apiVersion 0.0.1
     * @apiExample Example Usage
     * GET /example
     * @apiStop
     * 
     * Handle GET request
     * @return boolean
     */
    public function get()
    {
        // Handle GET request
        return true;
    }
}

[CodersBrothers]

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.

[cdtweb]

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.

[rottmann]

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';
    }

[cdtweb]

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!

[amregbaly]

@CodersBrothers could you please contact me amr@venatra.com