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-08-06 14:21:10

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Paul A. Bristow
> Sent: Monday, August 05, 2013 6:32 PM
> To: 'Discussion of Boost Documentation'
> Subject: Re: [Boost-docs] Problem linking functions/methods with Doxygen
> 
> > -----Original Message-----
> > From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf
> > Of Mathias Gaunard
> > Sent: Monday, August 05, 2013 2:52 PM
> > To: Discussion of Boost Documentation
> > Subject: Re: [Boost-docs] Problem linking functions/methods with
> > Doxygen
> >
> > On 17/07/2013 04:11, Kyle Lutz wrote:
> > > 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.
> 
> I have looked into this a bit more, and I also find that links using the "see also"
> 
> \see or \sa command
> 
> The links present in Doxygen output are not being passed through to Quickbook.
> 
> Two snips attached show the difference for a simple 'see also' Doxygen comment as
> 
> \sa sum(int, int) for a slightly useful function.
> 
> The quickbook section just shows plain text sum(int, int) instead of a link.
> 
> The source of html shows:
> 
> <p>sum(int, int) for a slightly useful function. </p>
> 
> There are NO messages relating to function sum in the Quickbook log
> 
> Am I doing something wrong or have I the wrong expectation of these links?
> 
> Paul
> 
> 
> ---
> Paul A. Bristow,
> Prizet Farmhouse, Kendal LA8 8AB  UK
> [phone]  07714330204
> pbristow_at_[hidden]
> 
> PS Although there are others for other examples of links that are missing:
> 
> Reference to method 'boost::mylibrary::myclass::test_me' is ambiguous. Found:
>               Match in namespace ::
>               Match in namespace ::
> Reference to method 'boost::mylibrary::myclass::test_me' is ambiguous. Found:
>               Match in namespace ::
>               Match in namespace ::
> Reference to method 'boost::mylibrary::myclass::test_me' is ambiguous. Found:
>               Match in namespace ::
>               Match in namespace ::
> Cannot find data-member named 'boost::mylibrary::mylibrary_global'
> Cannot find data-member named '::global_int'
> Cannot find data-member named 'boost::mylibrary::myclass.mypublic_var'
> Cannot find method named 'boost::mylibrary::myclass::mypublic_var'
> Cannot find method named 'boost::mylibrary::myclass.mypublic_var'
> Cannot find data-member named 'boost::mylibrary::myclass::myprivate_var'
> Cannot find class named 'std::exception'
> 
> but I think there may be other causes of this?

I've created a ticket #8972 for the missing links

https://svn.boost.org/trac/boost/ticket/8972

Doxygen \sa see also links are not passed to Quickbook C++ reference section.

(and BTW, failure to get a link is NOT caused by adding () to the function name - but needs to be
specified enough to be uniquely recognized - for example if you have more than one functions with
the same name but different parameters.  Global items need to prefixed by ::.  As specified in

http://www.stack.nl/~dimitri/doxygen/manual/autolink.html

)

Paul