Standard Source Documentation System: A new thread
Hi all, Our old thread, "Documentation System for Cold Fusion", seems to have wandered, as old threads are wont;-) Perhaps we might start afresh. There seems to be some confusion about proposed standards, etc, especially since Fred denies having any proposed anything (I think). Let me lay out the basic problem and requirements as I see them. It might then be fruitful to discuss whether these are complete/correct, before we proceed to discuss possible solutions. Please feel fee to slap me down if this is tedious or abhorrent;-) Here are the essentials that I propose for a general ColdFusion source-documentation standard: 1. Human readable/writable. Must be comprehensible to your most junior team members. 2. Machine readable/writable. Must be able to be parsed or written by machine, to allow development of future effort-saving software - browsers, CASE tools, who-knows-what. 3. Expandable. Must allow the creation of new comment-types, which can be tailored for use by individual organizations. Like HTML META tags. Take a'core' set, but you can add your own if you desire. 4. Free Positioning. Can be placed anywhere in the source code, as appropriate. 5. Applicable to ALL ColdFusion development, not just FuseBox. QUESTION: ARE WE AGREED AS TO THESES ESSENTIALS? Disgree with any? Want to add more? Once a particular standard general syntax is basically agreed on, then we have some other things to discuss, most importantly a standard core of comment types (eg, Description, responsibilities, attributes-with-Hal's-syntax, warning, author, designer, programmer, etc, etc, etc). Possibly a standard dictionary of synonyms would also be handy. After that, if we all begin to use the new syntax and core, we can look at devising the associated paraphenalia: 1. A standard structure for holding parsed documentation (like a Structure of Arrays of Strings); 2. An efficient parser to generate the above structure from standard code 3. Display modules for displaying the parsed structure in even-more-readble form. 4. An expandable browser-cum-test-bench that can integrate documentation display with other kinds of capability (eg, software metrics, unit testing). So the overall plan: 1. Standard General doc syntax 2. Standard core of comment types 3. Standard parsed structure 4. Parser 5. Display Module 6. Integrated browser 7. World domination. What do you all reckon??? Lee Borkman ([EMAIL PROTECTED]) http://bjork.net, ColdFusion Tags by Bjork Get free email and a permanent address at http://www.netaddress.com/?N=1 -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebarRsts&bodyRsts/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
RE: Standard Source Documentation System: A new thread
Great thread and very valuable. However, could we stop the cross-posting perhaps to multiple lists? I subscribe to both recipient lists and, with filters in place for each, I end up with four copies of every message in the thread. Very annoying. Ken -Original Message- From: Lee Borkman [mailto:[EMAIL PROTECTED]] Sent: Sunday, August 27, 2000 11:46 AM To: [EMAIL PROTECTED]; [EMAIL PROTECTED] Subject: Standard Source Documentation System: A new thread Hi all, Our old thread, "Documentation System for Cold Fusion", seems to have wandered, as old threads are wont;-) Perhaps we might start afresh. There seems to be some confusion about proposed standards, etc, especially since Fred denies having any proposed anything (I think). Let me lay out the basic problem and requirements as I see them. It might then be fruitful to discuss whether these are complete/correct, before we proceed to discuss possible solutions. Please feel fee to slap me down if this is tedious or abhorrent;-) Here are the essentials that I propose for a general ColdFusion source-documentation standard: 1. Human readable/writable. Must be comprehensible to your most junior team members. 2. Machine readable/writable. Must be able to be parsed or written by machine, to allow development of future effort-saving software - browsers, CASE tools, who-knows-what. 3. Expandable. Must allow the creation of new comment-types, which can be tailored for use by individual organizations. Like HTML META tags. Take a'core' set, but you can add your own if you desire. 4. Free Positioning. Can be placed anywhere in the source code, as appropriate. 5. Applicable to ALL ColdFusion development, not just FuseBox. QUESTION: ARE WE AGREED AS TO THESES ESSENTIALS? Disgree with any? Want to add more? Once a particular standard general syntax is basically agreed on, then we have some other things to discuss, most importantly a standard core of comment types (eg, Description, responsibilities, attributes-with-Hal's-syntax, warning, author, designer, programmer, etc, etc, etc). Possibly a standard dictionary of synonyms would also be handy. After that, if we all begin to use the new syntax and core, we can look at devising the associated paraphenalia: 1. A standard structure for holding parsed documentation (like a Structure of Arrays of Strings); 2. An efficient parser to generate the above structure from standard code 3. Display modules for displaying the parsed structure in even-more-readble form. 4. An expandable browser-cum-test-bench that can integrate documentation display with other kinds of capability (eg, software metrics, unit testing). So the overall plan: 1. Standard General doc syntax 2. Standard core of comment types 3. Standard parsed structure 4. Parser 5. Display Module 6. Integrated browser 7. World domination. What do you all reckon??? Lee Borkman ([EMAIL PROTECTED]) http://bjork.net, ColdFusion Tags by Bjork Get free email and a permanent address at http://www.netaddress.com/?N=1 -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=sts&body=sts/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body. -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
Re: Standard Source Documentation System: A new thread
All done, now my hands are really friggin tired. But there's my proposed "standard" of writing code if your really so hell bent on have a "standard" way of doing it. I presented this in a sarcastic manner mainly because I'm Fred and the thought of writing out this much extra commenting is a horrid thought. However, it is a good system and if your crew or company or whatever needs to spell everything out its not a bad system. If anybody wants to the see the really outdated original paper on PDL here's a link: http://www.cfg.com/pdl81/pdlpaper.html Now I'm going to watch a band or something. Later Guys and Gals, Fred - Original Message - From: "Lee Borkman" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]>; <[EMAIL PROTECTED]> Sent: Sunday, August 27, 2000 11:45 AM Subject: Standard Source Documentation System: A new thread Hi all, Our old thread, "Documentation System for Cold Fusion", seems to have wandered, as old threads are wont;-) Perhaps we might start afresh. There seems to be some confusion about proposed standards, etc, especially since Fred denies having any proposed anything (I think). -- clip clip - -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
Re: Standard Source Documentation System: A new thread
I'd personally like to apologize for the cross post when I hit reply I didn't pay attention (its late) to the TO: field. This was not supposed to come to this particular list. Sorry guys Fred -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
Re: Standard Source Documentation System: A new thread
Okay, I have been posting to FuseBox and CF-talk lists, because I think the topic is about ColdFusion development, not just FuseBox. Unfortunately, only the FuseBox lists members seem interested in the topic. SO... I am making this brave move and posting ONLY to CF-Talk. I suggest that we keep the discussion in that arena for now. Once a general standard (I have no fear of this word) for ColdFusion is proposed, then the FuseBox community can set about more specific FuseBox documentation, hopefully within the general standard. Now why the problem with the word "standard"? Surely a standard is just a recommendation, a proposed language/vocabulary, designed to help us all communicate clearly and with minimum fuss. Nobody is compelled to use it, but if they do, then it should make people's live easier, ie LESS miserable. I know what makes ME miserable... working on old code (mine or someone else's) and having absolutely no idea what the hell is going on. So to specifics (Hi Hal!), I propose the following for the GENERAL form of a FusionDoc (not just FuseBox) comment: As you can see, it's a normal CF comment, with an @ symbol immediately after the ". A single ":" separates the Commenttype from the CommentContent. The CommentContent may contain characters INCLUDING ":" and line-feeds/carriage-returns, but excluding "--->". I also propose that the CommentType can be ommitted: <---@ this comment has not CommentType, but should still be parsed ---> The FusionDoc comments may appear anywhere in the code, in any order, although the order should be significant (ie, retained by the parser). Multiple comments with the same CommentType are permitted, and should be handled sensibly by the parser. So that's it for my FusionDocs proposal. It's basically just a way of attaching particular comments to particular CommentTypes. NEXT... I have a second proposal, for a standard parser structure to contain the parsed FusionDoc documentation: A ColdFusion structure (ie, an Associative Array) of Arrays. The structure is indexed by CommentType. Each constituent array is an array of strings, containing the CommentContents (in order) of all related FusionDoc comments. One other element of the structure is needed to maintain the order in whihc the various CommentTypes appear. For this I currently use a list, CommentOrderList, but I see that that limits the use of the list-delimiter within the CommentType, so this should probably also be an array of strings. You can test drive this approach by grabbing my SourceBrowser from http://bjork.net. Thanks all, Lee Borkman 3rd World Get free email and a permanent address at http://www.netaddress.com/?N=1 -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebarRsts&bodyRsts/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
Re: Standard Source Documentation System: A new thread
I worked in Regulatory Space a bit, and one way we used to get around issues like this is to call it a "Guide" not a "Standard" best, paul At 01:59 PM 8/27/00 -0500, you wrote: >Once a general standard (I have no fear of this word) for ColdFusion -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=lists&body=lists/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
