| Re: IDL Documentation tool? [message #23387] |
Wed, 24 January 2001 00:45 |
plugge
Messages: 17
Registered: May 1995
|
Junior Member |
|
|
In article <3A6CCA1B.496CB694@ssrl.slac.stanford.edu>, Daniel Luebbert
<luebbert@ssrl.slac.stanford.edu> writes:
|>Hi there,
|>
|>I am trying to generate a documentation for a large bunch of IDL
|>programs of mine,
|>so that someone else could easily understand and use them.
|>Does anyone know of a program, PERL script, commercial tool or whatever
|>else
|>which could generate a complete documentation from the source code?
|>
|>It should certainly include a list of routines in each file, with the
|>respective arguments and keywords,
|>and also extra any header documentation like "doc_library" does.
|>But ideally it should also analyze which other routines each file uses,
|>maybe detect common block incompatibilities,
|>etc., etc...
|>
|>I know for instance that Java comes with a neat little program
|>"javadoc", which does much of the above.
|>If anybody is aware of something similar for IDL, I would be most
|>grateful for a hint.
|>
|>Daniel
Daniel,
some time ago I wrote a prettyprinter for IDL that could be a (first!!)
approach for your problem. It converts an IDL source file to LaTeX, optionally
generating an index of routines and common blocks and a table of contents.
I use it frequently to generate listings of the exercises done by the students
here (it is used also as a kind of printer filter for IDL).
If you are interested, I could send you an example .dvi or .ps file for an
first impression. The converter is freeware (GNU GPL) and comes with full
source; so you can modify it for your needs.
Best regards
Michael Plugge
|
|
|
|
| Re: IDL Documentation tool? [message #23397 is a reply to message #23387] |
Tue, 23 January 2001 07:34  |
James Kuyper
Messages: 425
Registered: March 2000
|
Senior Member |
|
|
Daniel Luebbert wrote:
>
> Hi there,
>
> I am trying to generate a documentation for a large bunch of IDL
> programs of mine,
> so that someone else could easily understand and use them.
> Does anyone know of a program, PERL script, commercial tool or whatever
> else
> which could generate a complete documentation from the source code?
No. That's fundamentally an impossible task. Complete documentation
includes things that don't reside in your source code and can't be
derived from it, such as a list of the requirements it must meet, a
description of how it fits into the larger picture, explanations of your
design decisions (including why you DIDN'T do certain things), a user's
guide, and the revision history.
Now, in any language that supports comments, you can insert those things
in your code, but they can't be derived from the code itself.
> It should certainly include a list of routines in each file, with the
> respective arguments and keywords,
> and also extra any header documentation like "doc_library" does.
> But ideally it should also analyze which other routines each file uses,
> maybe detect common block incompatibilities,
> etc., etc...
Those are all useful things to do; just don't confuse them with
"complete" documentation.
Unfortunately, I'm unaware of any existing facilities for collecting
such information from IDL files, but others may know more about such
things.
|
|
|
|
| Re: IDL Documentation tool? [message #23399 is a reply to message #23397] |
Mon, 22 January 2001 23:58 |
R.Bauer
Messages: 1424
Registered: November 1998
|
Senior Member |
|
|
Daniel Luebbert wrote:
>
> Hi there,
>
> I am trying to generate a documentation for a large bunch of IDL
> programs of mine,
> so that someone else could easily understand and use them.
> Does anyone know of a program, PERL script, commercial tool or whatever
> else
> which could generate a complete documentation from the source code?
>
> It should certainly include a list of routines in each file, with the
> respective arguments and keywords,
> and also extra any header documentation like "doc_library" does.
> But ideally it should also analyze which other routines each file uses,
> maybe detect common block incompatibilities,
> etc., etc...
Please have a look at the result of my catalog routine (unix/linux
the windows version has some restrictions)
http://www.fz-juelich.de/icg/icg1/idl_icglib/idl_source/idl_ html/idl_work_libraries.htm
The examples are extracted and you got them by clicking to the diamond
symbol.
The database card icon is used to see all routines each routine used.
Additional these files could be downloaded as tar.gz file or IDL 5.3 SAV
file.
(The windows Version is not able to tar gz)
If your mouse is over one of the routine names you will see the calling
sequence
If you click on the routine you get a separate window with the routine
from it's
orginial place. (or into idlde, this belongs to the settings of your
browser I prefer
IDL_SOURCE connected to the navigator)
Any failure in the header or if a routine doesn't compile is sampled in
a separate html file of each owner of the file. The author will be
informed
by email automaticly.
Please have a look to my reply too.
Re: check for duplicate routine names?
The catalog routines are written in IDL.
For further routines and licensing please look first at
http://www.fz-juelich.de/icg/icg1/idl_icglib/idl_lib_intro.h tml
http://www.fz-juelich.de/icg/icg1/idl_icglib/idl_source/idl_ html/dbase/download/catalog.tar.gz
http://www.fz-juelich.de/icg/icg1/idl_icglib/idl_source/idl_ html/dbase/download/catalog_db.tar.gz
More descrioptions of html and idl you will get in my publication
http://www.fz-juelich.de/zb/text/publikation/juel3786.html
regards
Reimar
--
Reimar Bauer
Institut fuer Stratosphaerische Chemie (ICG-1)
Forschungszentrum Juelich
email: R.Bauer@fz-juelich.de
=============================================
a IDL library at ForschungsZentrum J�lich
http://www.fz-juelich.de/icg/icg1/idl_icglib/idl_lib_intro.h tml
|
|
|
|
| Re: IDL Documentation tool? [message #23406 is a reply to message #23399] |
Mon, 22 January 2001 18:25 |
davidf
Messages: 2866
Registered: September 1996
|
Senior Member |
|
|
Jason P. Meyers (jpm7934@cis.rit.edu) writes:
> David: Why would you ever want to do this? Just go with the flow!
>
> Craig: Darn it! Why doesn't IDL have this in the first place? <grump>
>
> JD: You can do it with a combination of HISTOGRAM and REBIN...
>
> Pavel: Make sure it works on a Mac too!
>
> R. Bauer: See http://www.fz-juelich.de/ for licensing...
>
> Liam: Be sure to properly document your code and you will never have this
> problem.
>
> Newbie: Why won't colors work on my 24-bit screen?
>
> What a nice, comprehensive digest of comp.lang.idl-pvwave! :-)
Indeed. Now I feel comfortable going on a well-deserved
sabbatical to correct a problem with chronic crabbiness knowing
that I'll never be missed. :-)
Cheers,
David
P.S. Let's just say I had to laugh because my original
idea for a response to this question was to suggest
that one industrious day of hunting and pecking at
the keyboard would *certainly* be more appreciated by
end users than the results of any such hypothetical
documentation tool. :-)
--
David Fanning, Ph.D.
Fanning Software Consulting
Phone: 970-221-0438 E-Mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
Toll-Free IDL Book Orders: 1-888-461-0155
|
|
|
|
| Re: IDL Documentation tool? [message #23407 is a reply to message #23406] |
Mon, 22 January 2001 17:09 |
Paul van Delst
Messages: 364
Registered: March 1997
|
Senior Member |
|
|
Daniel Luebbert wrote:
>
> Hi there,
>
> I am trying to generate a documentation for a large bunch of IDL
> programs of mine,
> so that someone else could easily understand and use them.
> Does anyone know of a program, PERL script, commercial tool or whatever
> else
> which could generate a complete documentation from the source code?
Uhhh... don't you write the documentation *before* the code?
At first I thought MK_HTML_HELP would do the job, but you want something to actually go in and parse
the source code and hunt about for all the dependencies along with argument lists?
Jeez.
You'd still have to modify all the routine documentation so that other users know, say, what units
the various arguments are supposed to be in. Wot a job.
It sounds like a good project in which to learn Perl.... :o) Hmmm....
Good luck.
paulv
--
Paul van Delst A little learning is a dangerous thing;
CIMSS @ NOAA/NCEP Drink deep, or taste not the Pierian spring;
Ph: (301) 763-8000 x7274 There shallow draughts intoxicate the brain,
Fax: (301) 763-8545 And drinking largely sobers us again.
Email: pvandelst@ncep.noaa.gov Alexander Pope.
|
|
|
|
| Re: IDL Documentation tool? [message #23408 is a reply to message #23407] |
Mon, 22 January 2001 17:11 |
Jason P. Meyers
Messages: 24
Registered: September 2000
|
Junior Member |
|
|
Craig Markwardt wrote:
>
>
> David: Why would you ever want to do this? Just go with the flow!
>
> Craig: Darn it! Why doesn't IDL have this in the first place? <grump>
>
> JD: You can do it with a combination of HISTOGRAM and REBIN...
>
> Pavel: Make sure it works on a Mac too!
>
> R. Bauer: See http://www.fz-juelich.de/ for licensing...
>
> Liam: Be sure to properly document your code and you will never have this
> problem.
>
> Newbie: Why won't colors work on my 24-bit screen?
>
> Craig
>
What a nice, comprehensive digest of comp.lang.idl-pvwave! :-)
Jason Meyers
PhD Student, Center for Imaging Science
Rochester Institute of Technology
jpm7934@rit.edu
|
|
|
|
| Re: IDL Documentation tool? [message #23409 is a reply to message #23407] |
Mon, 22 January 2001 16:42 |
Craig Markwardt
Messages: 1869
Registered: November 1996
|
Senior Member |
|
|
Daniel Luebbert <luebbert@ssrl.slac.stanford.edu> writes:
> Hi there,
>
> I am trying to generate a documentation for a large bunch of IDL
> programs of mine,
> so that someone else could easily understand and use them.
> Does anyone know of a program, PERL script, commercial tool or whatever
> else
> which could generate a complete documentation from the source code?
>
> It should certainly include a list of routines in each file, with the
> respective arguments and keywords,
> and also extra any header documentation like "doc_library" does.
> But ideally it should also analyze which other routines each file uses,
> maybe detect common block incompatibilities,
> etc., etc...
David: Why would you ever want to do this? Just go with the flow!
Craig: Darn it! Why doesn't IDL have this in the first place? <grump>
JD: You can do it with a combination of HISTOGRAM and REBIN...
Pavel: Make sure it works on a Mac too!
R. Bauer: See http://www.fz-juelich.de/ for licensing...
Liam: Be sure to properly document your code and you will never have this
problem.
Newbie: Why won't colors work on my 24-bit screen?
Sarcasm aside, and it WAS SARCASM :-), yes Daniel, I think this would
be a wonderful addition to IDL, but I don't know of any such tool at
the moment.
Craig
P.S. No offense intended by anybody's inclusion or omission from the
list above. I was just having fun!
--
------------------------------------------------------------ --------------
Craig B. Markwardt, Ph.D. EMAIL: craigmnet@cow.physics.wisc.edu
Astrophysics, IDL, Finance, Derivatives | Remove "net" for better response
------------------------------------------------------------ --------------
|
|
|
|
comp.lang.idl-pvwave archive
Members
Search
Help
Login
Home
