cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marcus Sorensen <shadow...@gmail.com>
Subject Re: Api doc categories
Date Thu, 22 Aug 2013 16:41:20 GMT
Thanks, in looking through the mail history, I can see various
suggestions of adding categories to gen_toc.py, but I don't see a
concrete explanation of how this works. In experimenting it seems that
the category is matched against the api command name. That seems quite
limiting from a third party perspective, it means that vendors
offering plugins have to encode the category in the api name of every
command if they want it to fall under a specific category.

If this is true, it would be nice to have an optional category field
in the annotations to avoid mismatches. Take the netapp commands, for
example, some of them are things like 'associateLun', while others are
like 'listVolumesOnFiler'. An argument could be made that they need to
be renamed to include the word 'netapp', but as it stands, they might
create a netapp category and match anything with 'Lun' or 'Filer',
then when someone else comes along those keywords are taken.

On Thu, Aug 22, 2013 at 3:04 AM, Daan Hoogland <daan.hoogland@gmail.com> wrote:
> Marcus,
>
> I recall a mail in this list where a naming convention was mentioned.
> Look along those lines for categories.
>
> regards,
> Daan
>
> On Thu, Aug 22, 2013 at 6:46 AM, Marcus Sorensen <shadowsor@gmail.com> wrote:
>> I've spent a few minutes trying to figure out how API commands are linked
>> with their categories in the API documentation. I read the doc about
>> annotations and generating the docs. I see the known_categories in
>> gen_toc.py, but I don't see any place in the annotations where one might
>> define a specific command under a specific category. When I build I do see
>> it complain about uncategorized commands, such as the ones in the netapp
>> plugin (or whatever provides the 'filer' commands).

Mime
View raw message