From: "Jonathan Turkanis" <technews@kangaroologic.com>
Rob Stewart wrote:
From: "Jonathan Turkanis": Rob Stewart wrote:
From: "Jonathan Turkanis":
Yes, I was hoping to limit the interface to a single conversion operator. I'd hate to see someone just learning the library look up get() in the reference section, click on the return type and be confronted with a monstrous synopsis. Could I present a "fictional" synopsis of basic_character, which doesn't show all the overloads, and include a note explaining the problem?
What's fictional?. The operators to which you refer would not be implemented as members,
They might be friends implemented in-class.
Sure, but they aren't strictly part of basic_character's interface so they don't have to be in the synopsis for the class. Their being implemented as friends in the definition is an implementation detail that doesn't matter for documentation purposes.
Thus, I wouldn't call the result of their omission a fictional synopsis. Indeed, the meaning of "synopsis" means you can elide details.
I don't want to get distracted by the issue of whether the fact that an operator is defined in a friend declaration can be considered an implementation detail. My real question whether I can document the basic_character interface, broadly conceived, as simpler than it really is, and add a note explaining what's missing. I don't want a simple library element to require a huge section of documentation.
I'm not sure you got my point. I don't think you can avoid documenting the full interface of basic_character, including the namespace scope operators. However, you can provide a synopsis of the class that shows only the class members with a following section that discusses other functions that work with basic_character to give it a fuller interface. Thus, when clicking on the return type of get(), one sees a reasonably small class definition and discussion thereof. If one continues reading, one will learn about the namespace scope functions that augment that class' interface. If one doesn't continue reading, one simply returns to the previous page thinking basic_character is a pretty simple class. Indeed, one might write code using only that rudimentary knowledge of basic_character and, following the lead of the existing filters and examples, take advantage of the wider interface and not even notice. Eventually, such a one probably will wonder why certain expressions would work and will investigate the broader interface. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;