[postgis-devel] Doxygen linking is pretty neat

[Paragon Corporation]

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