Re: TIP #193: Simple Syntax Help System
From: Juan C. Gil (jgil_at_gmv.es)
Date: 05/11/04
- Next message: Andreas Wilm: "Re: POD-like code documentation"
- Previous message: Andreas Wilm: "Re: POD-like code documentation"
- In reply to: Bryan Schofield: "Re: TIP #193: Simple Syntax Help System"
- Next in thread: lvirden_at_yahoo.com: "SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
- Reply: lvirden_at_yahoo.com: "SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Date: 11 May 2004 01:54:30 -0700
Bryan Schofield <bschofield@users.sf.net> wrote in message news:<URTnc.16188$2f6.636577@twister.tampabay.rr.com>...
> Juan C. Gil wrote:
> > Donal K. Fellows <donal.k.fellows@man.ac.uk> wrote in message news:<pgpmoose.200404301106.19195@despot.non.net>...
> >
> >>TIP #193: SIMPLE SYNTAX HELP SYSTEM
> >>=====================================
> >>
> >
> > Excellent!
> >
> > The Simple Library (web site http://simplelib.bobsville.com/
> > currently down; write me directly if interested)
> > provides a similar introspection mechanism:
> >
> > [example elided]
> >
> > Juan Carlos---
>
> I had a few weeks ago mention some benefits of putting procedure headers
> just inside of the proc instead of just before. Just food for thought.
>
> http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&selm=vGMac.381618%24Po1.222418%40twister.tampabay.rr.com
>
I sure did read your posting with interest. In fact The
Simple Development Library (previously known as The Simple
Library; thanks Joe!) provides a homogeneous way to declare
programs, packages, commands, classes and methods. The
example above could be rewritten as:
package require SimplePackage
::Simple::Package::require-and-install SimpleDeclare
declare-proc {
foo
} -synopsis {
An simple procedure.
} -arguments {
{ a integer {An integer}}
{-b boolflag {A boolean flag}}
{-c word default {A flag}}
} -body {
puts "a = $a"
puts "b = $b"
puts "c = $c"
}
The great thing is that, while many elements in the declaration
serve just as documentation (-project, -synopsis, -overview,
-keywords, ... although they can be introspected), many others
are actually functional! For example, the -arguments flag give
a procedure or method arguments; there the type information is
informative by default, but can be put to work (that is, upon
invokation a command arguments can actually be checked for
type conformance). Other functional flags are -alias (which
defines a procedure or class alias), -access (which defines a
command or method access mode), -namespaces (which defines a
package namespaces), ... That way we routinely generate
documentation automatically from the code while honoring the
DRY (Don't Repeat Yourself!) principle.
Just for fun, the complete list of declarative tags is the
following: -access, -alias, -aliases, -arguments,
-assumptions, -attribute, -checktype, -class, -classes, -cmid,
-command, -commands, -constructor, -copyright, -destructor,
-details, -effects, -error, -examples, -exportedcommands,
-extends, -firsttimeinstall, -help, -history, -install,
-keywords, -limitations, -method, -methods, -module,
-namespaces, -option, -options, -overview, -package, -paradigm,
-parseflags, -program, -project, -references, -remarks,
-requisites, -resources, -returns, -smrs, -sprs, -stereotype,
-synopsis, -todo, -type, -uninstall, -usage, -variable and
-version.
My plan is to write a series of pages at the wiki describing
The Simple Development Library, which I really think is a
very useful tool for medium to big project development in Tcl.
Juan Carlos---
- Next message: Andreas Wilm: "Re: POD-like code documentation"
- Previous message: Andreas Wilm: "Re: POD-like code documentation"
- In reply to: Bryan Schofield: "Re: TIP #193: Simple Syntax Help System"
- Next in thread: lvirden_at_yahoo.com: "SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
- Reply: lvirden_at_yahoo.com: "SIMPLE question [Was: Re: TIP #193: Simple Syntax Help System"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Relevant Pages
|
