[postgis-devel] Doxygen linking is pretty neat

[Kevin Neufeld]

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#c2b06d67f4515dc04c6e2ecb645df452
>
> -- 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
>