Re: [Boost-docs] Problem linking functions/methods with Doxygen

Subject: Re: [Boost-docs] Problem linking functions/methods with Doxygen
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-07-17 14:34:08

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Kyle Lutz
> Sent: Wednesday, July 17, 2013 3:11 AM
> To: boost-docs_at_[hidden]
> Subject: [Boost-docs] Problem linking functions/methods with Doxygen
> 
> Hi,
> 
> I've recently updated my library [1] to use Doxygen for its reference documentation instead of
> BoostBook. The commit is here [2]. Overall it worked out great but I did encounter a few issues.
The
> largest is that function linking/referencing now longer seems to work :-(.
> 
> For example, on this page [3], the link to the "system::platforms()"
> method is not properly created. However, linking to other classes (such as "device" and "context")
on
> that same page works fine. This also occurs when linking to global functions (see the "See Also"
> section in [4]).
> 
> Is this a known bug or am I doing something wrong?
> 
> Thanks,
> Kyle
> 
> [1] https://github.com/kylelutz/compute
> [2] https://github.com/kylelutz/compute/commit/b539e8413c9d1942963a3d51b9f69d998ace2642
> [3] http://kylelutz.github.io/compute/boost/compute/platform.html
> [4] http://kylelutz.github.io/compute/boost/compute/copy.html

Nice!

This is what C++ Reference docs should be like :-) 

Automatically generated and with helpful comments and 'concepts/constraints'.  

As regards to the missing items, my experience is that it is worth running a build with standalone
Doxygen using the Doxywizard and selecting all warnings and sending these to a doxywarnings.txt log
file.  Doxygen gives some slightly more helpful comments on where it is confused - by the time it
has been through the mill of Quickbook ... these are often lost.  (I've found that it's also a lot
quicker to get rid of typos in the Doxygen comments as the Doxywizward only takes seconds to re-run.
But of course you won't have any of these ;-)

I try to get zero Doxywizard warnings before starting to add to Quickbook to generate the C++
Reference section.

HTH

Paul

PS I have a slight deja-vu feeling about global functions, but I can't remember what I concluded :-(

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]