Using extra CFC attributes for documentation
November 12, 2009 · Chris Peters
Using some extra CFC attributes and CFML's GetMetaData() function, we wrote a pretty cool documentation parser for CFWheels.
For the CFWheels API documentation, we chose to do something a little unconventional (but pretty cool). Using some extra CFC attributes and CFML’s GetMetaData() function, we wrote a pretty cool documentation parser for CFWheels.
Look at this example for the autoLink() view helper:
| <cffunction | |
| name="autoLink" | |
| returntype="string" | |
| access="public" | |
| output="false" | |
| hint="Turns all URLs and e-mail addresses into clickable links." | |
| examples=' | |
| ##autoLink("Download Wheels from http://cfwheels.org/download")## | |
| -> Download Wheels from <a href="http://cfwheels.org/download">http://cfwheels.org/download</a> | |
| ##autoLink("Email us at info@cfwheels.org")## | |
| -> Email us at <a href="mailto:info@cfwheels.org">info@cfwheels.org</a> | |
| ' | |
| categories="view-helper,text" | |
| functions="excerpt,highlight,simpleFormat,titleize,truncate" | |
| > | |
| <cfargument name="text" type="string" required="true" hint="The text to create links in."> | |
| <cfargument name="link" type="string" required="false" default="all" hint="Whether to link URLs, email addresses or both. Possible values are: `all` (default), `URLs` and `emailAddresses`."> | |
| <cfscript> | |
| var loc = {}; | |
| loc.urlRegex = "(?ix)([^(url=)|(href=)'""])(((https?)://([^:]+\:[^@]*@)?)([\d\w\-]+\.)?[\w\d\-\.]+\.(com|net|org|info|biz|tv|co\.uk|de|ro|it)(( / [\w\d\.\-@%\\\/:]* )+)?(\?[\w\d\?%,\.\/\##!@:=\+~_\-&]*(?<![\.]))?)"; | |
| loc.mailRegex = "(([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,}))"; | |
| loc.returnValue = arguments.text; | |
| if (arguments.link != "emailAddresses") | |
| loc.returnValue = loc.returnValue.ReplaceAll(loc.urlRegex, "$1<a href=""$2"">$2</a>"); | |
| if (arguments.link != "URLs") | |
| loc.returnValue = REReplaceNoCase(loc.returnValue, loc.mailRegex, "<a href=""mailto:\1"">\1</a>", "all"); | |
| </cfscript> | |
| <cfreturn loc.returnValue> | |
| </cffunction> |
It makes the function declarations a little beefier, but the documentation is right there with the code. As you can see, we added examples, categories, and functions attributes to the <cffunction> declaration.
Writing a parser took a little over a week, but it was fairly simple with CFML’s GetMetaData() function and some extra business rules.
See the autoLink() documentation on CFWheels.org so you can see what the output looks like. Everything on that page is generated based on the code above.
