SPEC - Specifying arguments.
David
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!)...
Regards,
David R
Isaac Dealey
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.
--
[ ike ] founder - onTap framework
phone: 781.769.0723
David R
Isaac Dealey
> 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. :)