comp.lang.idl-pvwave archive: archive

Home » Public Forums » archive » IDLDOC question

Show: Today's Messages :: Show Polls :: Message Navigator
E-mail to friend

Re: IDLDOC Question [message #74593 is a reply to message #66975]

Mon, 24 January 2011 15:39

Michael Galloy
Messages: 1114
Registered: April 2006

Senior Member

On 1/24/11 2:49 pm, David Fanning wrote:
> Mike, or whomever,
>
> What is the best way to document a program with IDLDOC when you
> really want to document the last module in the file. I'm thinking
> of FSC_Window, but I should think any widget program would have
> the same problem.
>
> I really like to have the program documentation at the top
> of the file, but if I understand IDLDOC correctly, the program
> documentation has to be immediately in front of the procedure
> or function definition statement that the documentation applies
> to. Is there any easy way around this restriction? Or, am I
> misunderstanding the restriction?

IDLdoc has both file-level and routine-level documentation headers. So
for a widget application you would probably have a file-level header
that describes the purpose of the application and a routine-level header
on the main routine to describe the parameters/keywords. Helper
routines, event handlers, cleanup routines, etc. would be marked private
so that they don't show up in user-level documentation. I would probably
do something like this:

; docformat = 'rst'

;+
; Documentation about how to use the application, like an example of
; of using it::
;
; IDL> mg_application, dist(20), some_keyword=5.
;
; This should produce output like:
;
; .. image:: screenshot.png
;-

;+
; :Private:
;-
pro mg_application_eventhandler_or_helperroutine, event
end

;+
; Documentation on call `MG_APPLICATION`.
;
; :Params:
; data : in, required, type=fltarr(n)
; special data to do something to
;
; :Keywords:
; some_keyword : in, optional, type=float
; specify something
;-
pro mg_application, data, some_keyword=someKeyword
end

If what you want it to do is document the parameters/keywords of the
main routine at the top of the file, there is no mechanism for doing
that. The "guiding philosophy" of IDLdoc is to place the documentation
for something as close as possible to the actual definition in the code
so that the documentation actually is updated as the code is updated. So
this means that documenting the params/keyword should happen immediately
before or after the "pro" or "function" line in the routine definition.

Mike
--
www.michaelgalloy.com
Research Mathematician
Tech-X Corporation

Report message to a moderator

[Message index]

		IDLDOC question By: David Gell on Mon, 29 June 2009 07:12
		Re: IDLDoc Question By: David Fanning on Thu, 11 November 2010 14:13
		Re: IDLDoc Question By: Michael Galloy on Fri, 12 November 2010 09:28
		Re: IDLDoc Question By: Michael Galloy on Thu, 11 November 2010 13:54
		Re: IDLDOC Question By: David Fanning on Tue, 25 January 2011 10:33
		Re: IDLDOC Question By: Paul Van Delst[1] on Tue, 25 January 2011 09:27
		Re: IDLDOC Question By: Michael Galloy on Mon, 24 January 2011 15:39
		Re: IDLDOC Question By: Jeremy Bailin on Thu, 20 October 2011 11:48
		Re: IDLDOC Question By: Michael Galloy on Thu, 20 October 2011 12:42
		Re: IDLDOC question By: Michael Galloy on Wed, 07 December 2011 19:03
		Re: IDLDOC question By: David Fanning on Wed, 07 December 2011 14:32
		Re: IDLDOC question By: manodeep@gmail.com on Wed, 07 December 2011 13:56
		Re: IDLDOC question By: David Fanning on Wed, 07 December 2011 14:07
		Re: IDLDOC question By: Brian Wolven on Wed, 07 December 2011 13:32
		Re: IDLDOC question By: David Fanning on Wed, 07 December 2011 13:13

Previous Topic:	Re: Removing Array Values
Next Topic:	Interpolation

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

] [

]

Current Time: Sat Oct 11 02:51:41 PDT 2025

Total time taken to generate the page: 1.36257 seconds