comp.lang.idl-pvwave archive: archive » Re: Using IDLdoc to format documentation

Home » Public Forums » archive » Re: Using IDLdoc to format documentation

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

Re: Using IDLdoc to format documentation [message #82750]

Fri, 18 January 2013 15:36

Matthew Argall
Messages: 286
Registered: October 2011

Senior Member

> Any thoughts?

I just recently started using IDLdoc and love it. I have been looking for something like it for my MatLab code. Seems like IDLdoc could work if I could just change the comment character to "%". Can there be a keyword for that?

Bullets would be good. Writing "1.", "2.", etc. has been easy enough for numerated lists. Especially for fixed-width fonts.

Report message to a moderator

Re: Using IDLdoc to format documentation [message #82790 is a reply to message #82750]

Thu, 17 January 2013 01:30

Mats Löfdahl
Messages: 263
Registered: January 2012

Senior Member

Den onsdagen den 16:e januari 2013 kl. 20:12:38 UTC+1 skrev David Gell:
> Thanks for the information. It seems like we all use the same work-around. The enumerated lists that Mike suggests would be helpful. I can thing of a number of places that bullet lists and numeric lists could be used.

I have a different workaround, I just insert empty (comment) lines where I want line breaks.

Like this:

; :RETURNS:
;
; -1 IF xUTC1 < xUTC2
;
; 0 IF xUTC1 == XUTC2
;
; 1 IF xUTC1 > XUTC2
;

Proper lists would sure be useful, though.

Report message to a moderator

Re: Using IDLdoc to format documentation [message #82793 is a reply to message #82790]

Wed, 16 January 2013 11:12

David Gell
Messages: 29
Registered: January 2009

Junior Member

Thanks for the information. It seems like we all use the same work-around. The enumerated lists that Mike suggests would be helpful. I can thing of a number of places that bullet lists and numeric lists could be used.

Report message to a moderator

Re: Using IDLdoc to format documentation [message #82820 is a reply to message #82793]

Tue, 15 January 2013 15:52

Michael Galloy
Messages: 1114
Registered: April 2006

Senior Member

On 1/15/13 4:20 PM, Phillip Bitzer wrote:
> Perhaps Mike (or someone else) can offer a different/better
> solution, but I usually do something like this:
>
> ; :Returns:
> ; One of three possible values are returned::
> ; -1 IF xUTC1 < xUTC2
> ; 0 IF xUTC1 == XUTC2
> ; 1 IF xUTC1 > XUTC2
>
> Similarly,
>
> ; :History:
> ; Modification history::
> ; 21 Mar 2007 D. A. Gell Initial coding
> ; 16 Apr 2007 D. A. Gell correct variable usage
> ; 7 Aug 2007 D. A. Gell added Kepler (dust) ram direction

Yes, I do things like that too, but find it awkward. I don't have a good
solution to this right now.

I would like to add itemized and enumerated lists to IDLdoc rst markup
with syntax something like:

; :Returns:
; One of three possible values are returned:
;
; * -1 if xUTC1 < xUTC2
; * 0 if xUTC1 == xUTC2
; * 1 if xUTC1 > xUTC2

and

; :History:
; * 21 Mar 2007 D. A. Gell Initial coding
; * 16 Apr 2007 D. A. Gell correct variable usage
; * 7 Aug 2007 D. A. Gell added Kepler (dust) ram direction

These would make simple bullet item lists (note that this would not
align the comparison operators in the first example).

Enumerated lists would look like:

; :Returns:
; One of three possible values are returned:
;
; 1. -1 if xUTC1 < xUTC2
; 2. 0 if xUTC1 == xUTC2
; 3. 1 if xUTC1 > xUTC2

or

; :Returns:
; One of three possible values are returned:
;
; #. -1 if xUTC1 < xUTC2
; #. 0 if xUTC1 == xUTC2
; #. 1 if xUTC1 > xUTC2

Any thoughts?

Mike
--
Michael Galloy
www.michaelgalloy.com
Modern IDL: A Guide to IDL Programming (http://modernidl.idldev.com)
Research Mathematician
Tech-X Corporation

Report message to a moderator

Re: Using IDLdoc to format documentation [message #82823 is a reply to message #82820]

Tue, 15 January 2013 15:20

Phillip Bitzer
Messages: 223
Registered: June 2006

Senior Member

Perhaps Mike (or someone else) can offer a different/better solution, but I usually do something like this:

; :Returns:
; One of three possible values are returned::
; -1 IF xUTC1 < xUTC2
; 0 IF xUTC1 == XUTC2
; 1 IF xUTC1 > XUTC2

Similarly,

; :History:
; Modification history::
; 21 Mar 2007 D. A. Gell Initial coding
; 16 Apr 2007 D. A. Gell correct variable usage
; 7 Aug 2007 D. A. Gell added Kepler (dust) ram direction

On Tuesday, January 15, 2013 3:09:57 PM UTC-6, David Gell wrote:
> I've got a couple of questions about using idldoc to format file documentation. First, I've a function that can return a status code. The header is formatted as follows:
>
>
>
> ; :RETURNS:
>
> ; -1 IF xUTC1 < xUTC2
>
> ; 0 IF xUTC1 == XUTC2
>
> ; 1 IF xUTC1 > XUTC2
>
>
>
> The idldoc output concatenates the 3 lines:
>
> Return Value
>
> -1 IF xUTC1 < xUTC2 0 IF xUTC1 == XUTC2 1 IF xUTC1 > XUTC2
>
>
>
> Is there a way to insure that the line breaks are maintained.

Report message to a moderator

Re: Using IDLdoc to format documentation [message #82857 is a reply to message #82820]

Tue, 22 January 2013 12:57

Ajean
Messages: 4
Registered: November 2012

Junior Member

On Tuesday, January 15, 2013 3:52:07 PM UTC-8, Mike Galloy wrote:
> On 1/15/13 4:20 PM, Phillip Bitzer wrote:
>
>> Perhaps Mike (or someone else) can offer a different/better
>
>> solution, but I usually do something like this:
>
>>
>
>> ; :Returns:
>
>> ; One of three possible values are returned::
>
>> ; -1 IF xUTC1 < xUTC2
>
>> ; 0 IF xUTC1 == XUTC2
>
>> ; 1 IF xUTC1 > XUTC2
>
>>
>
>> Similarly,
>
>>
>
>> ; :History:
>
>> ; Modification history::
>
>> ; 21 Mar 2007 D. A. Gell Initial coding
>
>> ; 16 Apr 2007 D. A. Gell correct variable usage
>
>> ; 7 Aug 2007 D. A. Gell added Kepler (dust) ram direction
>
>
>
> Yes, I do things like that too, but find it awkward. I don't have a good
>
> solution to this right now.
>
>
>
> I would like to add itemized and enumerated lists to IDLdoc rst markup
>
> with syntax something like:
>
>
>
> ; :Returns:
>
> ; One of three possible values are returned:
>
> ;
>
> ; * -1 if xUTC1 < xUTC2
>
> ; * 0 if xUTC1 == xUTC2
>
> ; * 1 if xUTC1 > xUTC2
>
>
>
> and
>
>
>
> ; :History:
>
> ; * 21 Mar 2007 D. A. Gell Initial coding
>
> ; * 16 Apr 2007 D. A. Gell correct variable usage
>
> ; * 7 Aug 2007 D. A. Gell added Kepler (dust) ram direction
>
>
>
> These would make simple bullet item lists (note that this would not
>
> align the comparison operators in the first example).
>
>
>
> Enumerated lists would look like:
>
>
>
> ; :Returns:
>
> ; One of three possible values are returned:
>
> ;
>
> ; 1. -1 if xUTC1 < xUTC2
>
> ; 2. 0 if xUTC1 == xUTC2
>
> ; 3. 1 if xUTC1 > xUTC2
>
>
>
> or
>
>
>
> ; :Returns:
>
> ; One of three possible values are returned:
>
> ;
>
> ; #. -1 if xUTC1 < xUTC2
>
> ; #. 0 if xUTC1 == xUTC2
>
> ; #. 1 if xUTC1 > xUTC2
>
>
>
> Any thoughts?
>
>
>
> Mike
>
> --
>
> Michael Galloy
>
> www.michaelgalloy.com
>
> Modern IDL: A Guide to IDL Programming (http://modernidl.idldev.com)
>
> Research Mathematician
>
> Tech-X Corporation

This would be lovely, actually ... there are several places I (like many others) am using :: in a funny way to make this happen. One more vote for this functionality!

Report message to a moderator

Re: Using IDLdoc to format documentation [message #82894 is a reply to message #82750]

Sun, 20 January 2013 10:21

Michael Galloy
Messages: 1114
Registered: April 2006

Senior Member

On 1/18/13 4:36 pm, Matthew Argall wrote:
>> Any thoughts?
>
> I just recently started using IDLdoc and love it. I have been looking
> for something like it for my MatLab code. Seems like IDLdoc could
> work if I could just change the comment character to "%". Can there
> be a keyword for that?
>
> Bullets would be good. Writing "1.", "2.", etc. has been easy enough
> for numerated lists. Especially for fixed-width fonts.
>

There are a lot of IDL specific issues in IDLdoc besides the comment
character. If you want to give it a try, take a look at
docparprofileparser__define.pro., particularly the _parseLines method.
There are a couple places where you can replace ';+' and ';' with the
appropriate characters for MATLAB. You will also have to change it from
looking for .pro files to looking to for MATLAB's extension.

Mike
--
Michael Galloy
www.michaelgalloy.com
Modern IDL: A Guide to IDL Programming (http://modernidl.idldev.com)
Research Mathematician
Tech-X Corporation

Report message to a moderator

Previous Topic:	Re: AstroPlotLib
Next Topic:	Re: Limit to input when creating a SAVE file?

-=] Back to Top [=-

[ Syndicate this forum (XML) ] [

] [

]

Current Time: Wed Oct 08 09:10:42 PDT 2025

Total time taken to generate the page: 0.00512 seconds