I document all variables with notes if they are: Public (this) Private to the CFC (variables) Private to a method (var within a cffunction). Arguments Environmental - (usually just CGI but also Url and Form when specified)
I like your concept of Abstract and would include a private as you've defined it. > I'm working on a doc generator for my CFC implementation and just want an > opinion: > > Should private variables be documented? > > Right now I've got three "Access" types for properties: > > "Public": These properties exist in the "this" scope. They can be > accessed > publicly or via special generic getter/setter functions (or, of course, > via > custom getter/setters). > > These are open, public properties > > "Abstract": These properties exist in the "variables" scope. They are > defined in my system such that they can be accessed via the generic > getter/setter functions (or, of course, via custom getter/setters). > > In other words they're "public" (sort of) but abstracted via getter/setter > methods. > > "Static": These properties exist in the "variables" scope. They are > defined > such that they can accessed via the generic getter but NOT the generic > setter. (Of course there's no way to stop you from building a custom > setter. Also Static structs or queries, being passed by reference are > also > updatable outside the component instance.) > > These are "read-only" properties (as long as you don't create a custom > setter). They are abstracted through the generic getter method but no the > setter. > > I'm considering adding "Private" which would also be in the "variables" > scope but would not be accessible by the generic getter/setter at all. > However they would be available to ancestor components. > > These would be useful really only for documentation. Also many of them > are > not available until the component "init()" method has been run (so if and > extended component failed to run super.init() then they might not be > available at all). > > If you were reading documentation on CFCs, would you want to see them or > not? > > I've already made the decision to display private methods in the docs (as > they're definitely available and useful to ancestors) but I'm torn about > private properties... > > (Please note that I'm not very familiar with Java either - I think that > the > names I've choosen are close to their Java meanings - or not in conflict > at > all - but I'm not sure. If the access names used strike you as really > stupid please recommend something different... I spent way too long trying > to come up with descriptive labels for this stuff. ;^) ) > > Jim Davis > > > > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Discover CFTicket - The leading ColdFusion Help Desk and Trouble Ticket application http://www.houseoffusion.com/banners/view.cfm?bannerid=48 Message: http://www.houseoffusion.com/lists.cfm/link=i:4:199383 Archives: http://www.houseoffusion.com/cf_lists/threads.cfm/4 Subscription: http://www.houseoffusion.com/lists.cfm/link=s:4 Unsubscribe: http://www.houseoffusion.com/cf_lists/unsubscribe.cfm?user=11502.10531.4 Donations & Support: http://www.houseoffusion.com/tiny.cfm/54
