Proper way to document or diagram custom event models in the DOM

Question

Imagine you have a bunch of components and subcomponents in your web application. You want to keep track of how all the custom events you added behave. Are there established ways to diagram or document these behaviors?

Here are some things the documentation should show:

1. The actual nesting of relevant DOM elements of the various components.
2. The names of events and where they're fired from.
3. Any payloads that are attached to the custom events (e.g. the contents of memo in a Prototype custom event.)
4. The places where events are observed.
5. Indications of what events are fired in response to other events.
6. Where events are allowed to bubble, and where they are stopped.

Answer 1

I've never heard of an established documentation standard for web application front-ends.

That said, since you've identified the different aspects of your application that you want to track, you could keep this info in a docblock for each event handler, and use the jsdoc toolkit to generate some inline docs.

IMHO, I think that since you know what it is that you want to document already, you should feel free to create documentation in whatever format makes the most sense for you, even if its completely unique to your app/organization. 8 hours on stackoverflow with no answers must mean there is no standard answer ;)

Answer 2

Honestly I used to LOVE visual modeler, and when MS dumped it for Visio I was somewhat disappointed.

That said, Visio is still a great tool, and you can use it for creating object models of components and defining events, properties, methods etc. It has some built in functionality for UML designs and all.

But I have to say in the end, I usually end up with notepad or MS word. Depending on how verbose you want to be with your documentation, typing up notes or a description for a component never really fits nicely into any kind of DOM tool, but you can bold, tab, list and italicize like a madman inside a Word doc.

Sounds sad, but it's true!