[postgis-devel] Doxygen linking is pretty neat

[Paragon Corporation]

Okay I'll experiment with that.  I kind of like the explicit brief though
since it allows you to have more than one sentence.  Wonder what happens if
you have it enabled and you have briefs if it does the explicit brief
behavior if specified and otherwise goes the assumed java brief way.

So I'll change to use the javadoc style and experiment with linking.



-----Original Message-----
From: postgis-devel-bounces at postgis.refractions.net
[mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of Kevin
Neufeld
Sent: Saturday, May 02, 2009 10:49 PM
To: PostGIS Development Discussion
Subject: Re: [postgis-devel] Doxygen linking is pretty neat

Yes, JavaDoc does have briefs - it's typically interpreted to be the first
sentence (or more precisely,  up to the first period) in a comment
description block. 

It looks like Doxygen does the same thing:
http://www.stack.nl/~dimitri/doxygen/config.html#cfg_javadoc_autobrief

The raster config file currently has this set to false, but feel free to
change that if you think it would help.

Also, as you noted, hyperlinking is done using the {@link method_name} tag
... I have no idea if this is respected in Doxygen though ... you'll have to
experiment.

-- Kevin


Paragon Corporation wrote:
> Kevin,
> Okay I see it here
>
> http://java.sun.com/j2se/javadoc/writingdoccomments/#tag
>
> But no @brief example or does javadoc always put description on the 
> front page for the file or perhaps that is a (configure feature in 
> Doxygen) thus not needing a brief tag.
>
> The linking style doesn't seem quite as simple and not sure how it 
> maps to the C world.
>
> Thanks,
> Regina
>
> -----Original Message-----
> From: postgis-devel-bounces at postgis.refractions.net
> [mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of 
> Paragon Corporation
> Sent: Saturday, May 02, 2009 8:59 PM
> To: 'PostGIS Development Discussion'
> Subject: RE: [postgis-devel] Doxygen linking is pretty neat
>
> Kevin,
>
> I'm pretty indifferent actually and the more that can support the 
> syntax the better assuming you get the same effect.  So given the 
> rt_api style -- would we simply just use  @ instead of \?
>
> Does javadoc style support the \brief or equivalent.  That was one 
> thing I saw lacking in the raster example below (so there short 
> descrips don't appear to show in the main file view
>
> http://postgis.refractions.net/documentation/raster-doxygen/df/d4b/rt_
> _api_8
> c.html
>
> Which I really liked with the \brief.
>
> Also how do you do hyperlinking in javadoc style?  That's the only 
> other thing I found really useful that I didn't see in the raster code.
>
> Thanks,
> Regina
>
>
>
> -----Original Message-----
> From: postgis-devel-bounces at postgis.refractions.net
> [mailto:postgis-devel-bounces at postgis.refractions.net] On Behalf Of 
> Kevin Neufeld
> Sent: Saturday, May 02, 2009 8:08 PM
> To: PostGIS Development Discussion
> Subject: Re: [postgis-devel] Doxygen linking is pretty neat
>
> Do you really like the Doxygen propriety style of comments?
>
> The JavaDOC style that the raster folks have adopted has the same effect.
> http://trac.osgeo.org/postgis/browser/spike/wktraster/rt_core/rt_api.h
> #L267
> produces...
> http://postgis.refractions.net/documentation/raster-doxygen/df/d4b/rt_
> _api_8
> c_c2b06d67f4515dc04c6e2ecb645df452.html#c2b06d67f4515dc04c6e2ecb645df4
> 52
>
> -- Kevin
>
>
> Paragon Corporation wrote:
>   
>> I've been playing around with making our code comments more Doxygen 
>> friendly.  The 2 most useful constructs I have found
>>
>> \brief  to make the comment appear as the short description for the 
>> function in list of functions \param  name parm -- description to 
>> describe each argument within the description \return description of 
>> return type -- which is really useful for C since there are some many 
>> ints that are enums and so forth
>>
>> And much sweeter -- within these you can include hyperlinks to other 
>> parts of the autogenerated docs simply by preceding class,function 
>> etc term with a #
>>
>> So for example I went in lwalgorithm.c and Doxygen sugar coated a 
>> description to something like
>>
>> /*!
>> ** \brief lwline_crossing_direction: returns the kind of 
>> #CG_LINE_CROSS_TYPE behavior  of 2 linestrings
>> ** \param l1 first line string
>> ** \param l2 second line string
>> ** \return a #CG_LINE_CROSS_TYPE
>> :
>> */
>>
>> This should appear soon in the autogenerated docs. 
>>
>> Thanks,
>> Regina
>>
>>
>> _______________________________________________
>> postgis-devel mailing list
>> postgis-devel at postgis.refractions.net
>> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>>   
>>     
> _______________________________________________
> postgis-devel mailing list
> postgis-devel at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>
>
>
> _______________________________________________
> postgis-devel mailing list
> postgis-devel at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>
>
> _______________________________________________
> postgis-devel mailing list
> postgis-devel at postgis.refractions.net
> http://postgis.refractions.net/mailman/listinfo/postgis-devel
>   
_______________________________________________
postgis-devel mailing list
postgis-devel at postgis.refractions.net
http://postgis.refractions.net/mailman/listinfo/postgis-devel