"incorrect identifier" warnings

[Broofa]

Hey Denis, the following comment is generating "[jgdoc] x/left appears
to be incorrect identifier" warnings:

/**
* @function $debugRect
* @param {Object} o An object that defines a rect by providing
one of each of the following properties
* @... {Number} x/left
* @... {Number} y/top
* @... {Number} w/width
* @... {Number} h/height
*/

While technically "x/left" is not a valid identifier this is, in fact,
how I want to document this method. I.e. the first thing I do in the
method is say "var x = o.x || o.left". Given this behavior, I think
this is a pretty reasonable way to document this method. Nor does
there seem to be a good alternative. (E.g. It seems a bit silly to
use @paramset to document each of the 16 possible variations)

Any suggestions on how this should be resolved? Frankly, I'd like to
just remove this check.

[denis.r...@gmail.com]

One suggestion I can offer at this moment is to have an option to
suppress this warning.
The other is to put those properties in a record and tag them all as
optional, providing description regarding the expected usage.

I had a version before that was not performing validations and that
lead to quite interesting side effects.
For example, if you would have a class with name MyClass/one (because
of typo) the rendered HTML would be broken.
I even entered a bug #42 for it :-)

Would that work for you guys?

Denis

[Broofa]

Uhm, I'm not sure what you mean by "put those properties in a record
and tag them as options".

If your talking about specifying a configuration setting, I don't
think that's appropriate. Configuration properties are used by
whoever admins jGD, but the identifiers are provided by the doc
authors.

[denis.r...@gmail.com]

what I meant is something like

/** @object Rect some comment */
/** @property {optional} x */
/** @property {optional} left */
....

I am quite positive that removing the check for good is a bad idea.
Been burned there.
Also another selling point (not a big one, but nevertheless) - I hope
at some point in the future there would be a way to create docs for
integration with IDEs. If the identifiers are not well-formed, that
would be problematic. But of course, it's a long shot.

Indeed config options are set by admins, but if an author has a
strong point that it should be changed, then it should not be a big
deal.

[Broofa]

On Feb 6, 4:46 am, denis.riabtc...@gmail.com wrote:
> what I meant is something like
>
> /** @object Rect some comment */
> /** @property {optional} x */
> /** @property {optional} left */
> ....

*yeesh* I don't think that's a good solution. It's too heavy-weight,
and doesn't really express what I want to communicate (that x *or*
left may specified, not that both should be present)

> Indeed config options are set by admins, but if an author has a
> strong point that it should be changed, then it should not be a big
> deal.

Hmm... I disagree. That's essentially saying that an author has two
choices: Either don't document the alternate property name, or go
track down the admin and justify why some particular property name
should be added to the config file. 99 times out of 100, the author
will just say, "screw it" and not bother with the alias.

Moreover, I think the ability to provide free-form identifier text is
useful in general.

What about this idea? Allow authors to place identifiers in quotes to
disable the identifier warning? E.g.

* @param {Number} "x/left" this doesn't cause a warning
* @param {Number} x/left ... but this does

If you find an unquoted, incorrect identifier, just log a warning that
reads:

x/left is not a valid identifier. Use quoted version - "x/left" -
to disable this warning

[denis.r...@gmail.com]

Ha, "Either don't document the alternate property name" - I recall
someone saying "too many synonyms are bad for users" :-) (just
kidding)

Seriously, the approach with quotes sounds a bit better.

Several thoughts though. While that might be reasonable for
parameters, it does not really make much sense for classes, functions,
etc. Simplest reason - you would have tons of headache referencing
these identifiers. For example, the character you've been using in
your case, "/" is used as path delimiter.

As a compromise I can suggest that this approach would be applicable
only to parameters and the following characters are not allowed: ",<,>
and & since they are not allowed in attributes of xml tags. And I am
not planning to redo all the XSLT transformations in order to enable
them :-)
That should cover 99.9999% of cases, I guess

Regards,
Denis