Comments on: Using extra CFC attributes for documentation

By: Chris Peters

Chris Peters — Thu, 19 Nov 2009 14:04:01 +0000

You just did, Tony. Thanks!

By: tony petruzzi

tony petruzzi — Thu, 19 Nov 2009 13:19:21 +0000

you might want to add a link in the article to the Documentation Guidelines particularly the section entitled Generating API Documentation in Core Source Code that explains all the attributes and what they mean.

By: Chris Peters

Chris Peters — Fri, 13 Nov 2009 18:34:47 +0000

The functions and chapters (not shown) attributes will associate the function documentation with related functions and chapters in the reference guide.

So you'll see something like this eventually at the bottom of each function's documentation:

Related Functions:

excerpt()
highlight()
simpleFormat()
titleize()
truncate()

I wanted to release something of value ASAP, so I decided to delay that functionality to a later iteration. Agile development works very well with volunteer work!

The categories attribute is used by the parser today to categorize the functions into a parentSectionId and childSectionId. It uses QoQ on a query of sections to translate the strings into IDs.

That's an interesting idea with cfinterface, but I like the idea of the examples being directly in there. Documentation authors can look at how the function works as they write the examples. Test writers can see how it should be tested when writing tests. Developers looking at the code can see how it should be used.

I agree that it is a drawback to have that extra stuff in there, but it is a matter of opinion on how pragmatic that it is. ;)

By: Russ S.

Russ S. — Thu, 12 Nov 2009 23:01:01 +0000

Cool idea, I like how it looks in the preview. Where does the categories and functions attributes come into play?
Maybe you could use cfInterface to get the example code out of the CFC file? That is really the only drawback.