Please document the following functions

[eschnett]

Please document, in the sense of describing the prototypes, i.e. the allowable arguments, of the following HPX functions:

• apply
• async
• then
• wait
• wait_all

I believe that these are the "magic" functions that take a variable number of arguments, and that are also heavily overloaded. A human-readable description may be better than a completely accurate set of C++ prototypes. Also, leaving out some details of these prototypes may improve readability.

I am looking for something like:

future<A>::then(f(future<A>, ...) -> future<B>, ...) -> future<B>

which would tell me that "then" takes one argument that is a function, and that that function needs to both expect and return a future.

Otherwise, I have trouble finding out whether this function should expect a future (or whether the future will be implicitly forced), or whether it should return a future or a direct value.

I do not much care about whether arguments are passed by copy or by reference or whether they are forwarded perfectly; this information should go into a separate description (if at all). My goal here is to avoid the 500 lines of compiler errors that, unfortunately, do not really tell me whether I should pass a future instead of a direct argument or vice versa.

These descriptions should also be "compact", in the sense that one may even abbreviate future<A> with F<A>. Adding hpx:: and ::lcos:: and ::naming_type will not add to readability; showing a few typedef and using declarations above the descriptions should make this possible without ambiguity.

It should also be possible to use fonts to distinguish between types and variables, and between Boost/HPX identifiers and "free" identifiers. In my example above, "future" and "then" are HPX identifiers, while A, B, and f are free in this sense.

[hkaiser]

These things are taken straight from the C++ standard and from additional proposals for standardization:

• C++11: http://isocpp.org/files/papers/N3690.pdf
• Improvements to std::future and Related APIs: http://isocpp.org/files/papers/N3721.pdf

The only thing you should need to do is to swap std:: for hpx::

[eschnett]

This document lists e.g.

template<typename F> auto then(F&& func) -> future<decltype(func(*this))>; 

which says that the argument of "then" is of type F and is called "func". This name tells me that it is a function, but does not document the types that func expects. I know I can decipher this by looking at the "decltype" and the "*this" part of the declaration. However, the alternative

future<A>::then(func(future<A>) -> B) -> future<B>

is much more readable: it omits the "template", "typename", and "&&" distractions (I know they are important for the compiler to obtain an unambiguous syntax), and shows the connection between the return types of "func" and "then" more clearly.

Am I expecting too much Haskell?

then :: future A -> (future A -> B) -> future B

[msimberg]

As this is a very fundamental part of hpx, would it be worth it to simply link to cppreference in our documentation (and the same for async, etc.). Or even use whatever text is on cppreference/in the proposals more or less verbatim?

What has been done so far with e.g. the parallel algorithms? It doesn't seem to match (in exact wording, not necessarily in implications) cppreference, but not quite the TS either.

[hkaiser]

What has been done so far with e.g. the parallel algorithms?

The docs we have for the algorithms were taken partially from the TS (very scarce), cppreference (we also directly link to the pages (see here for instance), and some home-grown prose. Most of the docs predate the cppreference pages.