akrzemi1 commented 7 months ago

The synopsis for parse() is missing relevant information:

Mandates: text_input<R> is true, error_handler<ErrorHandler> is true, attribute_compatible<Attr, R, Parser> is true.

Throws: whatever attribute copying or assignemt, or semantic actions throw. (something else?), std::bad_alloc?

Returns: true on successful parse, when the entire input is consumed; false otherwise.

Effects: on successful parse attr is assigned the value of the attribute produced by parser. On unsuccessful parse attr is assigned a default-constructed value.

And you may need a concept attribute_compatible or at least a "macro" for the purpose of documentation. You may also need to define what "successful parse" means.

tzlaine commented 7 months ago

109 covers the concept part. The rest is in the description already, just not formatted like this. The exception is the description of hhow the out-param is compatible with the default attribute. This is too much to repeat for each `*parse()` overload. The tutorial covers it, though.

akrzemi1 commented 7 months ago

So, it looks like you are saying that most of the function description is there, just not in a user-friendly format. I am requesting to provide a user-friendly format.

Some users will want to jump directly to the reference section and would expect to find all the relevant information here. Or at least the reference to other places that describe more generic properties. When the user wants to learn what parse() does, they will not know that prefix_prse() is almost the same. So from user's perspective such repetition one every *parse() function is rather helpful.

tzlaine / parser

Missing info in synopsis for `parse()` #103

109 covers the concept part. The rest is in the description already, just not formatted like this. The exception is the description of hhow the out-param is compatible with the default attribute. This is too much to repeat for each `*parse()` overload. The tutorial covers it, though.

tzlaine / parser

Missing info in synopsis for `parse()` #103

109 covers the concept part. The rest is in the description already, just not formatted like this. The exception is the description of hhow the out-param is compatible with the default attribute. This is too much to repeat for each *parse() overload. The tutorial covers it, though.

109 covers the concept part. The rest is in the description already, just not formatted like this. The exception is the description of hhow the out-param is compatible with the default attribute. This is too much to repeat for each `*parse()` overload. The tutorial covers it, though.