rfc doxygen+tcl
rene
I'm trying to enhance doxygen with tcl support.
You can find the current state at <http://wiki.tcl.tk/27011>
Comments are welcome.
rene
Harald Oehlmann
> I'm trying to enhance doxygen with tcl support.
Hi Rene,
I really would like to see doxygen support for TCL.
Is there a chance that it goes in the standard ?
Thank you,
Harald
rene
But a patch for ruby p.e. is not yet.
I don't know what is required to go in the standard distro.
Still I will try.
rene
nedbrek
"rene" <r.zau...@freenet.de> wrote in message
news:a2aef5e3-f5bd-47c8...@y3g2000vbm.googlegroups.com...
>
> I'm trying to enhance doxygen with tcl support.
>
> You can find the current state at <http://wiki.tcl.tk/27011>
>
> Comments are welcome.
Python has a commenting system that is accessible through the interpreter.
Is there any way we can have something like that (might have to be different
than pure doxygen...)
Ned
Robert Heller
I've written a Tcl-coded filter that 'generates' a pseudo C++ header. It
handles SNIT objects (snit::type, snit::widget, snit::widgetadaptor, and
snit::macro).
It is available at the URL
ftp://ftp.deepsoft.com/pub/deepwoods/Other/tcl2dox.tar.gz
Feel free to download it and have a look. It is pretty simple and does
what *I* need it to do.
>
>
--
Robert Heller -- Get the Deepwoods Software FireFox Toolbar!
Deepwoods Software -- Linux Installation and Administration
http://www.deepsoft.com/ -- Web Hosting, with CGI and Database
hel...@deepsoft.com -- Contract Programming: C/C++, Tcl/Tk
Arndt Roger Schneider
python docstring:
the comment is the first element of a def element.
You can do the same thing in Tcl:
proc my {
# This is a docstring equivalent commentary
# inside of a procedure...
...
}
Then write a help procedure which queries the
body of your proc...
help my =>
This is a docstring equivalent commentary
inside of a procedure...
... won't work for the c-part though.
-roger
--
BTW: Jeszra generates DocBook refentries from comments
and source code. See the API book at jeszra.sourceforge.net
for an example.
tom.rmadilo
wrote:
> nedbrek schrieb:
>
>
>
>
>
> > "rene" <r.zaums...@freenet.de> wrote in message
Tcl has both an engineering manual (C coding style) and a style guide
(Tcl coding style). If you follow these guidelines instead of those
required for doxygen you will get a better result, it will be much
easier for you and others to understand and maintain your code. These
guides cover more than just the non-code documentation.
nedbrek
"tom.rmadilo" <tom.r...@gmail.com> wrote in message
news:a0d70d4a-dbd5-498f...@g6g2000pro.googlegroups.com...
> On Sep 10, 6:46 am, Arndt Roger Schneider <arndt.ro...@addcom.de>
> wrote:
>> nedbrek schrieb:
>>> "rene" <r.zaums...@freenet.de> wrote in message
>>>news:a2aef5e3-f5bd-47c8...@y3g2000vbm.googlegroups.com...
>>
>>>>I'm trying to enhance doxygen with tcl support.
>>>>
>>>>You can find the current state at <http://wiki.tcl.tk/27011>
>>>>
>>>>Comments are welcome.
>>>
>>> Python has a commenting system that is accessible through the
>>> interpreter.
>>> Is there any way we can have something like that (might have to be
>>> different
>>> than pure doxygen...)
>
> Tcl has both an engineering manual (C coding style) and a style guide
> (Tcl coding style). If you follow these guidelines instead of those
> required for doxygen you will get a better result, it will be much
> easier for you and others to understand and maintain your code. These
> guides cover more than just the non-code documentation.
Cool, you are referring to http://wiki.tcl.tk/708
?
Funny I haven't read it until now.
Thanks!
Ned
nedbrek
"nedbrek" <ned...@yahoo.com> wrote in message
news:i6er7n$sst$1...@news.eternal-september.org...
I didn't see anything in there that would allow documentation to be
extracted in the interpreter. All the comments seem to be before the
"proc", which I believe get dropped...
Ned
Arndt Roger Schneider
Neither docstring nor comments in
tcl procedures are in any way related to doxygen.
The problem with python docstrings
or emacs help function --elisp features a similar mechanism:
Verbose comments disrupt internal code and the signature.
# In Tcl:
# general comment on procedure my.
proc my {} {
#! abstract on procedure my. !#
...
}
The ability to ask a function directly what it does,
from within an interactive tclshell,
is a nice-to-have feature.
-roger
Rob
Roger
There is already a product called Ruff! (written in Tcl), which looks like
it might achieve at least some of what the OP wanted. See
http://woof.magicsplat.com/ruff_home
I've looked though the documentation, but not used the product in any
rigorous way.
Rob.
nedbrek
"Arndt Roger Schneider" <arndt...@addcom.de> wrote in message
news:i6fe15$8ji$1...@speranza.aioe.org...
> tom.rmadilo schrieb:
>> On Sep 10, 6:46 am, Arndt Roger Schneider <arndt.ro...@addcom.de>
>> wrote:
>>
>>>nedbrek schrieb:
>>>>"rene" <r.zaums...@freenet.de> wrote in message
>>>>news:a2aef5e3-f5bd-47c8...@y3g2000vbm.googlegroups.com...
>>>
>>>>>I'm trying to enhance doxygen with tcl support.
>>>
>>>>>You can find the current state at <http://wiki.tcl.tk/27011>
>>>
>>>>>Comments are welcome.
>>>
>>>>Python has a commenting system that is accessible through the
>>>>interpreter.
>>>>Is there any way we can have something like that (might have to be
>>>>different
>>>>than pure doxygen...)
>>>
>>> the comment is the first element of a def element.
>>> You can do the same thing in Tcl:
>>>
>>> proc my {
>>> # This is a docstring equivalent commentary
>>> # inside of a procedure...
>>>
>>> ...
>>>
>>> }
>>>
>>> Then write a help procedure which queries the
>>> body of your proc...
>>>
>>> help my =>
>>> This is a docstring equivalent commentary
>>> inside of a procedure...
>>>
>>> ... won't work for the c-part though.
>>>
>>
>> (Tcl coding style). If you follow these guidelines instead of those
>> required for doxygen you will get a better result, it will be much
>> easier for you and others to understand and maintain your code. These
>> guides cover more than just the non-code documentation.
>
> Neither docstring nor comments in
> tcl procedures are in any way related to doxygen.
>
> The problem with python docstrings
> or emacs help function --elisp features a similar mechanism:
> Verbose comments disrupt internal code and the signature.
>
> # In Tcl:
> # general comment on procedure my.
> proc my {} {
> #! abstract on procedure my. !#
> ...
> }
>
> The ability to ask a function directly what it does,
> from within an interactive tclshell,
> is a nice-to-have feature.
>
I found some discussion of this in the wiki: http://wiki.tcl.tk/10793
It is also on the 9.0 wishlist...
Ned
tom.rmadilo
> "tom.rmadilo" <tom.rmad...@gmail.com> wrote in message
> > Tcl has both an engineering manual (C coding style) and a style guide
> > (Tcl coding style). If you follow these guidelines instead of those
> > required for doxygen you will get a better result, it will be much
> > easier for you and others to understand and maintain your code. These
> > guides cover more than just the non-code documentation.
> Cool, you are referring tohttp://wiki.tcl.tk/708
Here are the original PDFs:
http://tcl.sourceforge.net/engManual.pdf
http://www.tcl.tk/doc/styleGuide.pdf
But in general, public API should have their own manpages so users
don't have to look through your code to figure out how to use it.
Manpages can include examples of use, besides the stuff which might be
appropriate for a source code file.
Also, the coding guidelines referenced, if followed, reduce the need
for source code comments. Most guidelines are just conventions, a
choice between many possible choices, so it is easy to argue against
any of them. But it is difficult to argue for multiple guidelines for
documentation. To use doxygen in existing files, you would have to
edit them, leading to confusion in the version control history. It
would also be very difficult to document inline so called "object"
commands: procedures which have subcommands where the argument meaning
changes based upon the first arg.