Possibly support N4381-style function objects?

[timsong-cpp]

See N4381. These are global function objects that should be documented like functions, rather than objects. They are used extensively in range-v3.

[foonathan]

You can already override the entire synopsis of an entity with the \synopsis command, I plan on adding a command on changing the entity type name for the header as well.

With it you can completely override what an entity is.

[timsong-cpp]

This can split an entity into several, though. Consider:

struct foo_fn {
    // \requires XXXX
    template<class A, class B>
    void operator()(const A&, const B&) const; 

    // \requires YYYY
    // \returns ZZZZ
    template<class A, class B, class C>
    int operator()(const A&, const B&, const C&) const;
};

// \n4381_magic
constexpr inline foo_fn foo{};

Ideally the generated documentation should be as if for

// \requires XXXX
template<class A, class B>
void foo(const A&, const B&);

// \requires YYYY
// \returns ZZZZ
template<class A, class B, class C>
int foo(const A&, const B&, const C&);

[foonathan]

I definitely have plans for such advanced output manipulation, but this will probably take some time as I have other things prioritized.

[viboes]

@timsong-cpp The function object and the functions are not equivalent. So a reference documentation shouldn't do that.

The intent of the inline function object is to disable ADL when found in the first phase overload resolution lookup.

I believe that when we will have overload set (P0119) we could do the following

namespace xxx {
// \requires XXXX
template<class A, class B>
void foo(const A&, const B&);

// \requires YYYY
// \returns ZZZZ
template<class A, class B, class C>
int foo(const A&, const B&, const C&);
}
auto foo = xxx::foo;

Might the generated documentation will be ideal for you in this case?

[timsong-cpp]

The function object and the functions are not equivalent. So a reference documentation shouldn't do that.

I would rather have a blanket introductory paragraph explaining that they are actually function objects, but depicted as functions for simplicity and ease of understanding. That's far better than documenting them as "a constexpr function object of unspecified type that has the following overloaded function call operators".

[viboes]

"Standardese" could provide whatever features the author consider pertinent. Could you complete your example with reference to your introductory paragraph?

Would you prefer the standard Range TS be defined the way you are suggesting?

[timsong-cpp]

"The standard Range TS" is a different beast because it uses this only for actual customization points, where you need to specify a complicated set of lookup rules which is better done in words than code.

OTOH, the range-v3 use of this thing extends to plain algorithms and the like, whose counterpart is function templates in the range TS. This kind of uses is where a transformation like this is useful (the only reason I made this suggestion is because Eric Niebler suggested that I do it a few months ago...)

[viboes]

Ok. So you are not talking of the customization points then.

If this ticket don't pretend to take care of N4381-style customization point objects anymore, how would Standardese document such function objects?

Even for algorithms, I believe it is needed to document that the user is working with function objects as they are usable as HOF and be passed as arguments to other functions.

[timsong-cpp]

If this ticket don't pretend to take care of N4381-style customization point objects anymore, how would Standardese document such function objects?

Actual customization point objects with complicated overload resolution logic should probably be documented similar to the way they are documented in the ranges TS: "foo is a customization point object. The effect of calling foo(E) is as follows: x.foo() if that expression is well-formed; otherwise foo(x) with ADL, etc., etc." Presumably, this will have to be hand-written. I can't imagine automatically generating this stuff.

Even for algorithms, I believe it is needed to document that the user is working with function objects as they are usable as HOF and be passed as arguments to other functions.

Yes, and that can go into the hypothetical introductory paragraph somewhere.