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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Logware (www.logware.us): a new and convenient web-based time tracking application. Start tracking and documenting hours spent on a project or with a client with Logware today. Try it for free with a 15 day trial account. http://www.houseoffusion.com/banners/view.cfm?bannerid=67 Message: http://www.houseoffusion.com/lists.cfm/link=i:4:199381 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=89.70.4 Donations & Support: http://www.houseoffusion.com/tiny.cfm/54
