570850 - cfx docs parser - cannot have param with multiple type definitions

Status: RESOLVED WONTFIX

(Add-on SDK Graveyard :: Documentation, defect)

Description

[Noelle Murata]

This:

<api name="add">
@function
Adds a menu item to the context menu.
@param item {Item or Menu} `Item` or `Menu`. `Separator`s can't be added to the
top-level menu; an exception is thrown if attempted.
</api>

Should look something like:

add(item)

Adds a menu item to the context menu.
item               Item or Menu

Separators can't be added to the top-level menu; an exception is thrown if attempted.


But looks like:

add(item)

Adds a menu item to the context menu.
item               Item

or Menu Separators can't be added to the top-level menu; an exception is thrown if attempted.

Comment 1

[Brian Warner [:warner :bwarner]]

hm, would it suffice to use a comma or slash as a separator instead? That works already.. changing the parser to tolerate a space-separator will require more work.

 @param item {Item,Menu} blah

or

 @param item {Item/Menu} blah

what do you think?

A definite downside of not improving the parser is that folks who forget the convention will get quite failures like the one you saw, including if they combine the two (@param item {Item, Menu} blah).

Comment 2

[Myk Melez [:myk] [@mykmelez]]

The Add-on SDK is no longer a Mozilla Labs experiment and has become a big enough project to warrant its own Bugzilla product, so the "Add-on SDK" product has been created for it, and I am moving its bugs to that product.

To filter bugmail related to this change, filter on the word "looptid".

Comment 3

[Myk Melez [:myk] [@mykmelez]]

The workarounds in comment 1 seem sufficient.