I've confirmed that mismatches can happen, for example if you say both VPN and VPC in an api name. It would be nice to have an explicit annotation for doc category.
On Thu, Aug 22, 2013 at 10:41 AM, Marcus Sorensen <[email protected]> wrote: > 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 <[email protected]> > 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 <[email protected]> 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).
