RE: Documentation System for Cold Fusion
Hey Guys!! I was born, raised, and now currently live and work in one of those 3rd World countries you are making light of. Kindly recall that this is an international mailing list. Lee Borkman Sydney, Australia ps, there was a discussion going on about CF documentation standards, but I seem to have mislaid it, err.. lost the thread. --- "Hal Helms" [EMAIL PROTECTED] wrote: "Don't hide your light under a bushel. Be proud of who you are", my mom always says (or at least she did before I settled her into a lovely room she shares with 3 others at the U-Save Senior Center.) -Original Message- From: Nat Papovich [mailto:[EMAIL PROTECTED]] Sent: Saturday, August 26, 2000 1:49 PM To: '[EMAIL PROTECTED]' Subject: RE: Documentation System for Cold Fusion LOL, That's horrible Hal. You shouldn't brag about your cruelty. Nat Papovich ICQ 32676414 "Whatever you do may seem insignificant, but it is most important that you do it." -M. Gandhi -Original Message- From: Hal Helms [mailto:[EMAIL PROTECTED]] Sent: Saturday, August 26, 2000 4:26 PM To: [EMAIL PROTECTED] Subject: RE: Documentation System for Cold Fusion I like to think of myself as "enlightened", so our contract merely stipulates that we get the first-born and not all subsequent children (although we do have *options* on any additional kids). Sometimes I send them pictures of my fabulous house and expensive car with an encouraging note like "Don't you wish you were me?" Or I'll send a little note like: "I thought of you today as I finished a 12-minute phone call with the client and realized I made more on that call than you will in a month. Keep up the good work!!" I find that it's important to let workers know they're appreciated. I call it "sharing the wealth". The great thing is that it consists of warm smiles, encouraging notes, etc. -- but no actual cash outlay. It's funny how all my good fortune started when I met an intriguing fellow named Lou Cipher, who introduced me to these principles. -Original Message- From: Nat Papovich [mailto:[EMAIL PROTECTED]] Sent: Saturday, August 26, 2000 1:08 PM To: '[EMAIL PROTECTED]' Subject: RE: Documentation System for Cold Fusion Teach those improverished, underage workers, in third world countries Fusebox! We'll have the whole world at our mercy! Go NAFTA! NAT -Original Message- From: Hal Helms [mailto:[EMAIL PROTECTED]] Sent: Saturday, August 26, 2000 3:21 PM To: [EMAIL PROTECTED] Subject: RE: Documentation System for Cold Fusion I worked with the client to define an HTML prototype that looked EXACTLY like the real app. There was minimal code (almost none) but the idea was to give the client something they could work with--something tangible that would raise issues that usually only get raised once the client sees the real app. Once this was finalized, I did the architecture for the application, identifying the fuseboxes needed as well as any objects that would be used in the system (incorporating objects with Fusebox is a VERY interesting topic that I'll get into some day). From this architecture, I created fusestubs. This was the prototype page along with the fusedoc header. Of course, in some cases, there was no HTML page, so the fusestub was just the fusedoc itself. I had an SQL master do all the SQL as sprocs and had the Philippine coders use Nate Weiss's wonderful CF_DatalistsToQuery to simulate an actual query. This allowed me to get the code going before the fussy details of the database were done and meant that I didn't have coders writing SQL -- something I'm not a big fan of. Since the query files were all included (actually, I use them with CFMODULE, but you get the point), we swapped out the DatalistsToQuery files with the real SQL files. The switch was completely transparent. The only thing different was that real data started showing up. The Philippine coders had studied Fusedoc and Fusebox, so they were aware of how I wanted this coded. All they had to do was complete the responsibilities of the fusedoc, paying attention to the attributes. Typically, I got code back in three days, along with a test harness to allow me to unit test each fuse individually. -Original Message- From: paul smith [mailto:[EMAIL PROTECTED]] Sent: Saturday, August 26, 2000 6:46 AM To: [EMAIL PROTECTED] Subject: RE: Documentation System for Cold Fusion Interesting. I've been thinking about having work done through my contact in Russia. How did this work? Did they do CF only overseas? Or did they include text, too? Tell me more. This is why I've been following the Doc thread so closely. To use it not only in project definition, but also in communicating to those in Russia. best, paul At 07:15 PM 8/25/00 -0700, you wrote: Now, the interesting thing about this job is that all the code for this job was done overseas. Because of the time difference and the
Re: Documentation System for Cold Fusion
Yes, Hal's original FuseDoc syntax has two main aspects: 1. The -- notation for attribute specification; and 2. The high-level FuseDoc header syntax, which codes Responsibilities, Author, Attributes in a special order and manner. Now I like part 1, the attributes specification notation very much. But I don't think the overall FuseDoc header format is flexible enough to become universal. So I am proposing a more flexible high-level syntax, which is completely compatible with Hal's attribute specification notation. For example, here is the "FusionDocs" header for one of my fuses: !---@ Description: Retrieves directory information into a query --- !---@ Designer: Lee Borkman ([EMAIL PROTECTED]) --- !---@ Programmer: Lee Borkman ([EMAIL PROTECTED]) --- !---@ Thanks: Uses Nate Weiss' QuerySort tag if available. Thanks Nate --- !---@ Attributes:-- [directory]: An absolute directory (eg, c:\cfdocs\)--- !---@ Attributes:-- [sortBy]: a SORT clause for the directory listing (defaults to alpha) --- !---@ Attributes:-- [filter]: an optional file filter (eg, *.cfm) (not yet implemented) --- !---@ Attributes:-- CALLER.dir: a WDDX query of directory data --- You can see that it's pretty much equivalent to one of Hal's FuseDoc headers, just as readable with some familiarity, and that it uses the same attribute notation. It is, however, easier to parse, and allows more flexibility in the number, order and type of comment (eg, the Thanks to Nate). This can, of course, easily be parsed into XML or WDDX, though my own parser currently builds a CF Structure of Arrays of Strings. Keep up the goods work all, Lee. http://bjork.net "John Quarto-vonTivadar" [EMAIL PROTECTED] wrote: I liked the visually directional nature of Hal's suggested Fusedoc. (I think the brackets one is more recent than the others, tho, I don't recall it from the CFDJ article?). I would suggestion simply using Lee's method of preceeding each line with !---@ (or somesuch) since it defines each individual element and then Hal's directional "thingies" since they given further break down info...it's almost the equivalent of: fusedoc attributes type="variable" required="no" scope="ATTRIBUTES" description="put user name here"UserName/attributes attributes type="variable" required="yes" scope="APPLICATION" description="PKID in DB"DSN/attributes attributes type="file" stressedout="Jennifer" callmethod="customtag"formula2attributes/attributes /fusedoc i think a melding of Lee and Hal's method accomplishes this and also lets us convert to the quasi-XML above -John 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?sidebarRstsbodyRsts/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
RE: Documentation System for Cold Fusion
Well, I am very fond of Hal's specific syntax for documenting attributes (--, --, ++, [], etc). Nicely pictorial, so easy to understand/write for developers of various levels. I am concerned, however, with how to embed this kind of documentation into a more general doc format. Here are the essentials that I see: 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. 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" that can integrate documentation display with other kinds of capability (eg, software metrics, unit testing). So the plan as I see it: 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. Perhaps we need to summarise the candidates for a General doc syntax, so we can think about the first hurdle before worrying about which browser we prefer? Any thoughts? Lee Borkman ([EMAIL PROTECTED]) http://bjork.net, ColdFusion Tags by Bjork "Hal Helms" [EMAIL PROTECTED] wrote: But i LIKE to squat! And I do it so well. OK, I'm giving a talk on Fusedoc at the upcoming Fusebox conference, so this is a good time to be talking about this stuff. First, tell me what you DON'T like about the present style. A quick refresher: -- userID: NUMERIC, a primary key from USERS table This indicates that an attribute will be explicitly passed into the fuse and provides info on it -- [userID]: NUMERIC, a primary key from USERS table indicates an optional parameter - userID: NUMERIC, a primary key from USERS table indicates a "pass-thru" parameter, a var that is passed directly into AND out of the fuse without change ++ application.userID: NUMERIC, a primary key from USERS table indicates a global variable +++ myFile.cfm indicates an include file needed for this fuse to run Each incoming symbol has an outgoing symbol for its counterpart so that -- is matched with -- and so forth. Here's what a real fusedoc looks like from a recent job I did: !-- CartSummary.cfm -- !-- [EMAIL PROTECTED] -- !--- || Responsibilities: I show the user's cart summary based on the cookie "cartID" that exists. If no cookie exists, I tell the user they don't have anything in their cart. || -- RFA.continueShopping: a FUSEACTION -- RFA.removeItemFromCart: a FUSEACTION -- RFA.retotalCart: a FUSEACTION called when the Update_partID_quantity is changed -- RFA.checkout: a FUSEACTION - fatherID: a STRING - fatherType: a STRING ( Certification | Manufacturer | ProductLine | HotDeals | searchString) default = Manufacturer - fatherName: a STRING -- partID: PRIMARY KEY from Parts table on RFA.removeItemFromCart @DeveloperNote: The ampersand indicates that this will be replaced by a value at run time. For example, a valid variable name might be "Update_2107_1" -- Update_partID_quantity: a NUMBER on RFA.retotalCart (may be multiple) ++ [cartID]: a COOKIE PRIMARY KEY from Carts table. +++ qryGetCartSummary.cfm +++ incHeader.cfm +++ incFooter.cfm || END FUSEDOC--- Now, the interesting thing about this job is that all the code for this job was done overseas. Because of the time difference and the high cost of phone calls, the only viable communication method we had was email. As it turned out, almost no communication was required, as the coders understood how Fusedoc worked and the fusestub contained all the info they needed to create the code. Can we improve on this? If so, I welcome ideas. -Original Message- From: John Foulds [mailto:[EMAIL PROTECTED]] Sent: Friday, August 25, 2000 10:22 AM To: [EMAIL PROTECTED] Subject: Re: Documentation System for Cold Fusion Not only too darn hard to read, too
Re: Documentation System for Cold Fusion
http://www.cfm-resources.com/members/cfdoc/syntax.htm returns 404 ~Justin - Original Message - From: "Paul Johnston" [EMAIL PROTECTED] To: "Fusebox" [EMAIL PROTECTED]; "Cf-Talk" [EMAIL PROTECTED] Sent: Wednesday, August 23, 2000 12:25 PM Subject: Documentation System for Cold Fusion Due to the lack of interest in my last posting, I am re-posting (sort of) a mail to get some feedback. I have created a documentation system called cfdoc. I know there are others, but they all seem a little complex for me, and not so transferrable and useful in other circumstances. It took me about an hour to create it, and it now has a web page where you can download the browser that I made, and there is also a syntax reference. It is similar to Plain Old Documentation (as in Perldoc) because it is similar in style, simple, and straightforward to use. Please have a look, and download it. You can modify the code, but please tell me before making any major changes. The web site is http://www.cfm-resources.com/members/cfdoc/ Again, feedback would be really helpful. Thanks Paul -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=listsbody=lists/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=listsbody=lists/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
RE: Documentation System for Cold Fusion
Where did you get the link from? I'm a bit confused. The front page should show syntax.cfm not .htm and I can't find any other link. Paul -Original Message- From: JustinMacCarthy [mailto:[EMAIL PROTECTED]] Sent: 23 August 2000 12:40 To: [EMAIL PROTECTED] Subject: Re: Documentation System for Cold Fusion http://www.cfm-resources.com/members/cfdoc/syntax.htm returns 404 ~Justin - Original Message - From: "Paul Johnston" [EMAIL PROTECTED] To: "Fusebox" [EMAIL PROTECTED]; "Cf-Talk" [EMAIL PROTECTED] Sent: Wednesday, August 23, 2000 12:25 PM Subject: Documentation System for Cold Fusion Due to the lack of interest in my last posting, I am re-posting (sort of) a mail to get some feedback. I have created a documentation system called cfdoc. I know there are others, but they all seem a little complex for me, and not so transferrable and useful in other circumstances. It took me about an hour to create it, and it now has a web page where you can download the browser that I made, and there is also a syntax reference. It is similar to Plain Old Documentation (as in Perldoc) because it is similar in style, simple, and straightforward to use. Please have a look, and download it. You can modify the code, but please tell me before making any major changes. The web site is http://www.cfm-resources.com/members/cfdoc/ Again, feedback would be really helpful. Thanks Paul -- Archives: http://www.mail-archive.com/cf-talk@houseoffusion.com/ To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=listsbody=lists/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=listsbody=lists/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=listsbody=lists/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
Re: Documentation System for Cold Fusion
Hi John, My intention here is to devise a documentation syntax that will be applicable to ALL ColdFusion development, not just FuseBox. I personally love FuseBox, but it has its detractors. My feeling was that the original FuseDoc header used by Hal was too inflexible. I wanted to add other kinds of comment like Version Histroy, Warning, Contact, Charge Code, etc. I have therefore devised my proposed syntax (based on JavaDoc) so that any developer or group can invent their own set of "standard" comment types, and so the FusionDoc syntax is flexible enough to support this. eg., !---@ Description: This is a nice little template --- !---@ Warning: This template won't work on Solaris --- !---@ Variable: tmp: local, integer, used as a loop index --- The comments have an @ to identify them as FusionDoc format, then a Commenttype, then the CommentContent. That's all. The CF_FusionDocs parser turns the FusionDoc comments into a Structure of Arrays of Strings, which can then be used by a display engine (eg my SourceBrowser) to do all kinds of tricks. Hal has suggested that the FusionDoc syntax could allow additional formats that would have extra meaning, eg, !---% Variable: x. This variable is required, as indicated by the % in the comment --- That's not a great example, but is roughly the idea. I would prefer it, though, if any extra information was encoded into the CommentContent, instead of expanding the FusionDoc syntax. Another parser could break down the CommentContent once FusionDoc parser is finished. Does that make sense? I think that would keep the basic syntax both simple and flexible. Anyway, sorry for the blurb. I agree that it's a pain to contemplate switching standards. That's why I have spent some time talking with Hal, trying to build something that is not a dead-end. thanks for listening, Leeb. - "John Quarto-vonTivadar" [EMAIL PROTECTED] wrote: Hal, do you subscribe to the modified form of Fusedox that Lee seems to be using? Either way works but in order to move the tool forward some of the Fusedoc should stabilize. I just realized how usefull Lee's tool could be with some expansions, yet I also have 8-10 complete sites already done in the "old" (??) Fusedoc style (remember START FUSEDOC and END FUSEDOC )? Absolutely, Lee. I'll get it up there within the next day or so. I think what Lee did is excellent and I hope we can continue to evolve Fusedoc to where it does a good job of meeting everyone's needs. -- To Unsubscribe visit http://www.houseoffusion.com/index.cfm?sidebar=listsbody=lists/fusebox or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body. 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?sidebarRstsbodyRsts/cf_talk or send a message to [EMAIL PROTECTED] with 'unsubscribe' in the body.
