proto::function undocumented for use in grammars

[John Maddock]

There's no documentation on what template argumentes proto::function takes when defining grammars.

Also it appears that proto::function enables the function call operator for protoized types, as well as being used by functions that need to return lazy expressions. This dual use and how to restrict or prevent function call operator overloading should also be documented.

[Joel Falcou]

proto::function is mainly to activate operator()(...) on proto types. Th euse of this tag as a way to define new function int he doc is just an exampel tied to the default_context. A better (as in more scalable) way to do so (lazy function) is to use make_expr as shown later.

I'll amend the documentation for the operator()() use case.

[Eric Niebler]

John, there is really nothing special to say about proto::function distinct from all the other operator metafunctions in Proto. The multiple uses of these metafunction is discussed ​here. Is that insufficient?

Also, proto::function doesn't "enable the function call operator for protoized types," which makes me think you were trying to say something else(?). Functions that need to return lazy expressions /could/ use proto::function (it is a metafuntion that generates expressions, as described in the above link), but the better tool for that job is proto::make_expr.

I feel like you went looking for something in the docs and didn't find it, but I'm not entirely sure what. Now that you know a little more, and you know where in the docs it's described, do you have any suggestions for making the docs more useful?

[Joel Falcou]

Eric i wonder if the example of making a new lazy function using proto::function is not detrimental and should be replaced/removed so the better make_expr solution is more proeminent.

[anonymous]

Eric, Joe,

My apologies, but this was all a while ago and I haven't used proto since the original discussion on the mailing list. I did look at the link you gave, but was short on time and just got more confused - I see no mention of lazy functions or proto::function there? So <shrug> I guess. I'm sorry I can't be more helpful, but there's something that just isn't clicking for me I guess :-(

[Eric Niebler]

John, the link I gave doesn't specifically talk about proto::function, but it makes a general point about all of Proto's operator metafunctions -- of which there are a great many, including proto::function -- namely, that they can be used in many different capacities. They can compute new expression type, match those type, and transform those types. This seems to be one of those things that all new users of Proto struggle with. It's worth considering whether it indicates a flaw in Proto's design, a flaw in Proto's docs, or if it's Just One Of Those Things, like Haskell's monads, that are powerful but inherently hard to grok.

Joel, I had another look at the docs about creating lazy functions, and you're right. I overemphasize proto::function's role by a lot. I took another crack at it. Have a look ​here.

Closing this as fixed, but will continue to think about the overloaded (ab)use of Proto's operator metafunctions for Proto-11.