Re: [Boost-docs] Reference to overloaded function from quickbook to doxygen

Subject: Re: [Boost-docs] Reference to overloaded function from quickbook to doxygen
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2014-12-16 14:48:55

Thank you for your answer.

It does not seem like overload is helping in this case. The documentation of doxygen indicates that this might be used for overloaded *member* functions, so maybe this is the reason (using 1.8.6 BTW). The XML produced does not show any key that would enable the distinction of these 3 overloads, even with this keyword.

Right now I am writing all overloads in the quickbook doc. This is a pity as the added value of doxygen here is to have the API doc in sync with the code. 
As far as I remember, I saw in the past some doc in boost that are including the source code in the quickbook and are putting quickbook tags in it, and at the same time defining a macro that prevents doxygen from parsing the already documented content. 
I think this is really getting into an infinite loop and very hard to maintain in the long term.

I liked your idea of defining every overloads in one place. But in that case, the “overload” keyword is useless I think.

Best,
Raffi Enficiaud

> On 16 Dec 2014, at 08:21, Antony Polukhin <antoshkka_at_[hidden]> wrote:
> 
> 2014-12-09 13:47 GMT+03:00 Raffi Enficiaud <raffi.enficiaud_at_[hidden] <mailto:raffi.enficiaud_at_[hidden]>>:
> <...>
> Each of the 3 overloads in doxygen have their own documentation. When I look at the xml generated from doxygen, the 3 functions are there, but they all (obviously) have the same name and I cannot see a way of distinguishing them.
> 
> Is there any known workaround for this issue (either in the quickbook and/or in the doxygen documentation)? 
> 
> I've been hit by this issue a few months ago. Solution would be to describe all the overloads on a single page. Use Doxugen `\overload` keyword for that:
> https://github.com/apolukhin/Boost.DLL/blob/master/include/boost/dll/import_function.hpp#L99 <https://github.com/apolukhin/Boost.DLL/blob/master/include/boost/dll/import_function.hpp#L99>
> 
> Solution looks not very nice at first, but then I get used to it and even liked it: functions with same names must do the same thing, so they must be described once instead of multiple copypasted Doxygen descriptions all around the source code. 
> 
> Describing all the overloads at once is a popular approach. See for example http://www.cplusplus.com/reference/string/string/insert/ <http://www.cplusplus.com/reference/string/string/insert/>
> 
> -- 
> Best regards,
> Antony Polukhin
> _______________________________________________
> Boost-docs mailing list
> Boost-docs_at_[hidden]
> http://lists.boost.org/mailman/listinfo.cgi/boost-docs