Documenting Handlers and Request Collection values

Communities ColdBox HMVC
1

My apologies if this has been asked before or documented elsewhere. I’ve been looking “everywhere” and haven’t found anything.

I love ColdFusion’s component explorer (you know, the one you get when you go to cf_root/wwwroot/CFIDE/componentutils/componentdoc.cfm ?). I’m trying to get our team to make better use of it so they can reuse code more. Model objects are wonderful for this as the component explorer writes out all the arguments needed for each method, etc. However, with handlers, values aren’t passed as arguments, per say; they are all bundled together inside the event argument. This doesn’t help to document which keys in the request collection a handler is expecting to see. I’ve thought about adding extra argument tags inside each handler action, but then you wouldn’t be able to specify required attributes, and this isn’t the way coldbox works anyway, so you would probably end up confusing other developers. I’ve also thought about adding metadata attributes to the functions such as ‘rcParams’ or somthing and then modifying the component explorer to look for and write out that content. But that’s no better than just using the ‘hint’ attribute. Has anyone else wanted to see better documentation of handlers? I’m curious to know what others have done about this.

Thanks in advance,
Tim.

2

Hi Tim,

I believe there was a request to add something like this in 3.5 but i haven’t had time to check if it made it in. Actually…just checked the list and it appears it may be an ask for 4.5 - http://groups.google.com/group/coldbox/browse_thread/thread/3d4f32c464a6af8f/0f676d7021eb93c4?lnk=gst&q=3.5#0f676d7021eb93c4

Look at the thread from Aaron Greenlee at 2:52pm. I believe this would achieve what you’re looking for from a security standpoint - i.e only permitting certain vars to be passed into a handler function. Given Luis’ love for documentation I’m sure if a feature like this was added, the ability to document would also be a feature. Adding as metadata seems like a valid approach in order to support documentation. If you’re looking to build this sooner than later then maybe you could do a pull request and get it into a point release? I know I would certainly find this feature valuable.

Regards,

Nolan

3

Wow very interesting. Ideas?

4

A good place to start may be to take a look at fusedocs. I'm not
suggesting you copy the XML syntax, but it is a methodology that has
been out there in the real world with some success. I expect you could
do something similar with metadata