Allow more generous event names

[pigulla]

Note: I vaguely remember this being discussed before, but I couldn't find the corresponding issue. Forgive me if a decision about this has already been made.

I'm currently documenting code that uses Backbone which fires events with names such as change:myattribute. Unfortunately, jsduck doesn't support this and thinks the annotation @fires change:myattribute means the event's name is simply change (and considers :myattribute to be its documentation).

I can see how some people may want to fire events that include spaces (e.g., awesome event) and then everything goes downhill from there. Maybe allow the event names to be wrapped in curly braces:

/**
 * Does foo stuff.
 * @fires {my:bar}
 */
function foo() {
    // ...
}

Then again, that would probably require changes to the @link tag as well :-(

Thoughts?

[nene]

Yep, it's an old issue, that has popped up time and time again.

So far my stance has been that all class and member names should be proper JavaScript identifiers, because if I open up this jar of additional characters, there's no end to it... eventually I would need to support all possible characters. And that's not quite so easy to implement.

And it brings along a whole slew of corner cases. Like on one day somebody wants to name his events as change#myattribute, and now he would like to link to these, but, ahemm... {@link Class#change#myattribute}.

However... it looks like I do need to finally solve this problem.

There's a related pull request #487 to allow hyphens in class names, but it has backwards-compatibility issues and it's not really a full fix for the whole issue.

Inside doc-comments, there are basically two reasonable approaches to allow extra characters:

/**
 * @fires "my#bar" - Quoting
 * @fires my\#bar - Escaping
 */

Actually, for characters that don't have a special meaning for JSDuck, we could easily read the whole thing until a space or some other special character is encountered:

/** @fires my:bar */

But this would limit our choices if we'd like to give some special meaning to the : char in future. So I'd better limit the scope of this to quoting and escaping (which can both be supported simultaneously).

Similar problems arise on the UI side, where we currently can't handle class names containing dashes:

#!/api/Ext.My-Component-event-foo

But I think we can again use the same escaping:

#!/api/Ext.My\-Component-event-foo

Or in URL-encoded way:

#!/api/Ext.My%5C%2DComponent-event-foo

So that's the general arhitecture/syntax to go for. When will I get to implementing it is another question.

[mikaelkaron]

:+1: for fixing this (our event names look like dom/click)

[Riplexus]

Any chance of fixing this issue? We ran into this Problem as well by using periods in @cfg names. Renaming them is not viable and we would love to find a way to document them in a clean way.

[michaelkantor]

Would be nice if there was an option to work around the "proper javascript name" limitation with quotes, brackets, braces, or some other tool that declares "parse this name until the closing quote/brace/bracket".

Proper users can still use:

@fires myEvent

And those of us with other needs can use one of these:

@fires [my:event] @fires my:event @fires "my:event" @fires my:event