On Wed, 08 Jun 2005 16:06:17 +0200 Tobias Schwinger <tschwinger@neoscientists.org> wrote:
I did document them "just in case", because there might be some corner-cases in which their use is more efficient or convenient. It seems safe to remove them from the documentation to me ITM, but I want to think some more about it before doing so. Another option could be to move their description to a comment in the header.
If they are kept, however, I see the documentation should be changed to make a very clear recommendation not to use them, unless having good reasons.
I think the question is not of whether they should be documented, but whether they should be exposed. If they are exposed, then they should be documented. If you do not want them to be used, then protect them, or put them in the detail namespace. On what is necessary to leave as a viable user interface, only use will really tell. I have found it much easier to broaden a restricted interface than the inverse (mostly because once you provide the interface, someone is bound to use it, if for no other reason than it exists).