Re: [v3] pb_ds fixes for debug mode, valgrind

[Jonathan Wakely <jwakely dot gcc at gmail dot com>]

On 24 May 2011 18:45, Benjamin Kosnik wrote:
>
>> The trick I'm using for allocator_traits (where I'm making heavy use
>> of decltype) is:
>>
>> private:
>> ? typedef decltype(expr) __type;
>> public:
>> ? typedef __type type; ?///< type
>>
>> The private type isn't documented, so the end result is pretty good -
>> seeing the complex decltype expression doesn't help users anyway.
>
> I am unfamiliar with "///<" markup. And don't see this in the current
> generated docs.... show me a page or link to current web doxygen?

That markup is generated here:
http://www.stack.nl/~dimitri/doxygen/docblocks.html#memberdoc

But that wasn't what I meant to draw attention to, my point was that
doxygen gets very confused by:

public:
  typedef decltype( complex_expr<foo>(bar) ) type;

And documents "type" as a public member function not a type.

But if you do this:

private:
  typedef decltype( _S_expr<_Foo>(_Bar) ) __type;
public:
  typedef __type type;

Then doxygen ignores the private bit and correctly documents "type" as
a type, and the complex expression using uglified names is hidden from
users reading the docs.

> Sadly this is an area where macros make the generated doxygen output
> cleaner, because you can just configure doxygen to deal with macros.
>
> Lemme know if you have any ideas about derived template types. I am
> planning on just grouping correctly for the modules and living without
> correct hierarchy diagrams for the moment. To my great annoyance.
>
>> For deleted functions I suggest:
>>
>> ? /// Deleted copy constructor
>> ? foo(const foo&) = delete;
>>
>> Otherwise doxygen just includes it with no indication it's deleted.
>
> Ah. We should be putting this into the doxygen style guide.

Good idea.  See once_flag in the current API docs for an example where
doxygen implies it has a copy constructor and assignment operator, but
actually they're deleted.