I understand that SPEC is OnTap's way of doing fusedocs, However in
Fusedocs we can classify arguments under <in> and <out> blocks (which
in turn comes handy while documenting the fusedocs).
Does SPEC have anything like that?.. (I've not gone through the xsd
yet though!)...
> I understand that SPEC is OnTap's way of doing fusedocs, However in > Fusedocs we can classify arguments under <in> and <out> blocks (which > in turn comes handy while documenting the fusedocs).
> Does SPEC have anything like that?.. (I've not gone through the xsd > yet though!)...
Hi David, thanks for contributing. :)
The XSD for SPEC was created oh... wow... long time ago. :) And due to a general lack of involvement in the project it's never really become popular or been updated... It's always worked of course for documenting functions and custom tags, which was part of the reason for not using FuseDocs in the first place, because the semantic of FuseDoc was really designed to cover a problem domain that didn't include functions or custom tags.
SPEC really should be its own open-source project rather than being bundled with the onTap framework, because it was designed with the intent of being generic enough to support a wide variety of common programming languages. So the same SPEC document could be used for projects in ColdFusion, Java, ASP, PHP, Ruby, C#, etc. Granted that because there is so much variation in languages, it's not going to be able to cover them all. It's unlikely for example that you could reasonably model many LISP programs using it. And I'm not sure what you would do with functions like ColdFusion's onMissingMethod() or Ruby's doesNotUnderstand() that allow the function names to be declared dynamically and take arguments from portions of the function's name, i.e. Gateway.findBy_categoryid_7().
There are a lot of things in the XSD that I've not looked at in several years, for example, I remember that I had designed it to map out file structures (directories and files) and to map out database schemas all in the same document. The idea behind doing that was to get all the resources for a given project or application described simply in a single document to give you a sort of "site map" of your code.
So getting back to your question, I *think* there are some "results" nodes defined in the XSD for individual files, so you can declare variables required/created by a particular file (and iirc the semantic of "results" also allows you to indicate new directories, files, database tables, etc. that might be created albeit less often). But I'd have to go back and look through the XSD myself at this point because I've only really used it for functions and custom tags for a long time.
Thanks for the detailed response Issac!.. Being a fusebox coder for a long time, and very much addtictive to the FLIP methodology, I thought it would be apt to start OnTap with SPEC (like we do fusedocing in Fusebox).
On Tue, Sep 9, 2008 at 12:41 AM, Isaac Dealey <i...@tapogee.com> wrote:
> > I understand that SPEC is OnTap's way of doing fusedocs, However in > > Fusedocs we can classify arguments under <in> and <out> blocks (which > > in turn comes handy while documenting the fusedocs).
> > Does SPEC have anything like that?.. (I've not gone through the xsd > > yet though!)...
> Hi David, thanks for contributing. :)
> The XSD for SPEC was created oh... wow... long time ago. :) And due to a > general lack of involvement in the project it's never really become > popular or been updated... It's always worked of course for documenting > functions and custom tags, which was part of the reason for not using > FuseDocs in the first place, because the semantic of FuseDoc was really > designed to cover a problem domain that didn't include functions or > custom tags.
> SPEC really should be its own open-source project rather than being > bundled with the onTap framework, because it was designed with the > intent of being generic enough to support a wide variety of common > programming languages. So the same SPEC document could be used for > projects in ColdFusion, Java, ASP, PHP, Ruby, C#, etc. Granted that > because there is so much variation in languages, it's not going to be > able to cover them all. It's unlikely for example that you could > reasonably model many LISP programs using it. And I'm not sure what you > would do with functions like ColdFusion's onMissingMethod() or Ruby's > doesNotUnderstand() that allow the function names to be declared > dynamically and take arguments from portions of the function's name, i.e. > Gateway.findBy_categoryid_7().
> There are a lot of things in the XSD that I've not looked at in several > years, for example, I remember that I had designed it to map out file > structures (directories and files) and to map out database schemas all > in the same document. The idea behind doing that was to get all the > resources for a given project or application described simply in a > single document to give you a sort of "site map" of your code.
> So getting back to your question, I *think* there are some "results" > nodes defined in the XSD for individual files, so you can declare > variables required/created by a particular file (and iirc the semantic > of "results" also allows you to indicate new directories, files, > database tables, etc. that might be created albeit less often). But I'd > have to go back and look through the XSD myself at this point because > I've only really used it for functions and custom tags for a long time.
> Thanks for the detailed response Issac!.. Being a fusebox coder for a > long time, and very much addtictive to the FLIP methodology, I thought > it would be apt to start OnTap with SPEC (like we do fusedocing in > Fusebox).
> Just started learning this new framework!.
That makes perfect sense. :)
It may also make sense to think about re-conceptualizing the way that FuseDocs are traditionally embedded in the file when moving to the onTap framework. I'm not saying that you definitely want to (or don't want to) but rather that, you might want to consider some options.
For example as you're putting together an onTap framework application, you're going to have files like /_local/100_myapp.cfm.
This file is likely to be in that directory there all by itself at first, because probably additional files in that directory would only be created by plugins or by people looking to customize your application for their own use.
So it may make more sense to you (you'll have to judge for yourself) to place the SPEC information in a separate file in that directory. You might create something like /_local/_spec.cfm. That would keep it up top in the directory listings and then you always know where the spec is, regardless of how many templates might eventually be in that directory.
Alternately you might place the spec document outside the framework's special directories. So for example if you had the event /store/index/ the /_tap/store/index/ directory may contain /_application, /_htmlhead, /_local, /_layout.cfm and possibly /_process.cfm and /_onrequestend. All these directories and the files in them are related to /store/index/ so you might like to have a single xml fragment that documents them all in one place like /_tap/store/index/_spec.cfm. That way all the functional documentation for that event node is grouped in one place and looking at the one doc you can see if and how files in /_application/ and /_local/ interact.
p.s. prefixing a directory or file with an underscore like _spec.cfm will prevent it from being accessed in a browser, which is good for protecting the code from potentially malicious users. :)
|
