Re: [Boost-docs] Quickbook links to functions with the same name but different parameter lists

Subject: Re: [Boost-docs] Quickbook links to functions with the same name but different parameter lists
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-05-29 07:55:41

> -----Original Message-----
> From: Boost-docs [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of Daniel James
> Sent: Tuesday, May 28, 2013 11:45 PM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] Quickbook links to functions with the same name but different parameter
lists
> 
> This is all bad news...

Well thanks for warning me ;-)

 
> On 28 May 2013 09:50, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> > [memberref boost::mylibrary::myclass::test_me(float)]
> 
> Resolving links to reference documentation is part of boostbook. I don't know much about it, but I
don't
> think it supports linking to individual overloads.

It produces the right links OK, but the "ambiguous functions" message is confusing - but you can
easily ignore it.
 
> > [memberref boost::mylibrary::myclass::test_me(int, const char*)
> > boost::mylibrary::myclass::test_me(int, const char*)]
> 
> Quickbook uses spaces as a separator, and doesn't have a good way of quoting values, so I don't
think
> there's much that can be done here.
> Not in the short term anyway. But doesn't really matter if the boostbook support is there.

Yes - fine - a feature not a bug.   Might be worth documenting, but it's pretty obvious what to do
if you meet it.
> 
> > But I couldn't get a truly global variable to be referenced
> >
> > int const global_int = 99; // [globalref ::global_int]
> >
> > but maybe that's because they are non-PC? ;-)
> 
> Have you checked that reference documentation for global_int was actually created? I vaguely
recall
> that it wasn't for doxygen docs for some reason.

That would explain it.  
 
> > Nor could I get a link from *class* public (or private) member variables.
> 
> I don't think Boostbook has any support for linking to member variables. 'memberref' actually
generates
> a tag called 'methodref' for linking to methods. I don't know why it was done that way.

OK - it isn't a feature (And not a feature you often really, really want).

So there is Good News after all -  I wasn't being stupid and missing something.

Results of refactoring circular_buffer are looking good to me - will post soon when I get it through
the inspect test.

What proved *very tiresome indeed* was the inconsistent layout of files in Boost - so getting all
the links to Boost.XXXX docs was very annoying.

IMO a major objective for the GIT transformation must be to ensure consistency in how you get to the
index.html for the docs, tests, examples, sources... so that links to these are obvious.

Thanks, as ever.

Paul

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