| Re: IDLDoc Bandwagon [message #72657 is a reply to message #72510] |
Mon, 20 September 2010 20:54   |
Michael Galloy
Messages: 1114
Registered: April 2006
|
Senior Member |
|
|
On 9/20/10 5:48 pm, David Fanning wrote:
> Folks,
>
> I have been wanting to get on the IDLDoc bandwagon
> for awhile now. But I have never been able to successfully
> get reasonable looking output from any of my (apparently
> feeble) attempts to get it to work.
>
> Today I downloaded the very latest from Mike's web page,
> and spent most of the afternoon trying one combination
> after the other. Nearly all of my attempts, no matter
> what I set the FORMAT_STYLE keyword to, end up looking
> like a dog's dish with all my comments slammed together
> in a single paragraph.
>
> I'm usually no good at figuring these kinds of things out,
> but I have spent enough time on it that I would have
> expected to be *somewhere* by now. Line endings seem
> somehow to be involved, so I thought I would just ask,
> has anyone gotten this to work on a Windows machine?
One thing that has slowed me down on the most recent release of IDLdoc
is that it will have actual documentation: both a tutorial and a
reference manual! Hopefully, these will help people learn how to get the
comments formatted usefully.
But, in the meantime, you are correct, the FORMAT_STYLE and MARKUP_STYLE
determine how the comments are formatted in the output. Looking at some
of the code in your library, it looks like you probably should use
FORMAT_STYLE='IDL' and MARKUP_STYLE='preformatted' (it won't look good,
but should be readable). The MARKUP_STYLE='preformatted' will make
linefeeds significant. You will also need to make the comment header
(i.e., the part between ;+ and ;-) be next to the routine prototype (the
pro/function line), like:
;+
; NAME:
; BITGET
;
; PURPOSE:
;
; Returns the bit value (0 or 1) of a specified bit in a supplied
; number.
;
; AUTHOR:
;
; FANNING SOFTWARE CONSULTING
; David Fanning, Ph.D.
; 1645 Sheely Drive
; Fort Collins, CO 80526 USA
; Phone: 970-221-0438
; E-mail: davidf@dfanning.com
; Coyote's Guide to IDL Programming: http://www.dfanning.com
;
; CATEGORY:
;
; Utilities
;
; CALLING SEQUENCE:
;
; bitValue = BitGet(number, bit)
;
; INPUT_PARAMETERS:
;
; number: The input number. Should be a scalar integer.
; If not, it is converted to
; one by rounding.
;
; bit: The number of the bit you are interested in. A
; value between 0 and 63.
; If not supplied, all 64 bit values of the
; number are returned. May be an array of bit
; numbers.
;
; OUTPUT_PARAMETERS:
;
; bitValue: The value, 0 or 1, of the specified bit in the
; number.
;
; KEYWORDS:
;
; SILENT: If set, suppresses informational messages
; regarding rounding operations.
;
; MODIFICATION HISTORY:
;
; Written by David W. Fanning, 14 June 2006.
;-
FUNCTION BitGet, value, bit, SILENT=silent
Note, I recommend using FORMAT_STYLE='rst', MARKUP_STYLE='rst' for new
comments, in which case the header would look like:
;+
; Returns the bit value (0 or 1) of a specified bit in a supplied
; number.
;
; :Categories:
; utilities
;
; :Author:
; ::
;
; FANNING SOFTWARE CONSULTING
; David Fanning, Ph.D.
; 1645 Sheely Drive
; Fort Collins, CO 80526 USA
; Phone: 970-221-0438
; E-mail: davidf@dfanning.com
; Coyote's Guide to IDL Programming: http://www.dfanning.com
;
; :History:
; Written by David W. Fanning, 14 June 2006.
;
; :Params:
; value : in, required, type=integer
; The input number. Should be a scalar integer. If not, it is
; converted to one by rounding.
; bit : in, optional, type=integer
; The value, 0 or 1, of the specified bit in the number.
;
; :Keywords:
; silent : in, optional, type=boolean
; If set, suppresses informational messages regarding rounding
; operations.
;-
FUNCTION BitGet, value, bit, SILENT=silent
It's painful to convert existing files, so individual files can specify
their own FORMAT_STYLE/MARKUP_STYLE by putting a "docformat" comment on
the *first line* of the file, like:
; docformat = 'rst rst'
or
; docformat = 'IDL preformatted'
Anyway, I hope to have something a bit more complete by the way of
documentation out soon.
Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation
|
|
|
|
comp.lang.idl-pvwave archive
Members
Search
Help
Login
Home
