[postgis-devel] Doxygen linking is pretty neat

[Paragon Corporation]

Kevin,

Okay I just played around with linking and it seems the equivalent javadoc
is 

{@link #whatever}

It's a bit more verbose, but I can live with it

The 
@see #whatever

Creates a 
See Also section which is useful too. 

I think we should also fiddle around with the css so our dev documentation
has more of the same look as our user documentation, but that can come
later.

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 9:06 PM
To: 'PostGIS Development Discussion'
Subject: RE: [postgis-devel] Doxygen linking is pretty neat

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