On 06/11/2014 13:02, Jan Stolarek wrote:
Sometimes we add flags that are for experimentation or development purposes and not intended for user consumption, and these tend not to be added to the User's Guide. I suspect many of the flags you mention fall into this category. I suggest for these we have a specific comment in the source "developer use only; undocumented" so that we know they don't need to go in the User's Guide. I don't like that policy. What if some of the mentioned flags could be useful for my development work but I have no idea how to use these flags because they are not documented? I think we should have these documented as well, possibly with a note saying that this is experimental/unstable.
Requiring that all experimental flags be fully documented in the User's Guide is both too onerous for the developer, and too confusing for users, IMO. It's a User's Guide, not a developer's guide, after all! The developer has access to the source code, so they can find out what a flag actually does, and if it's not obvious then a comment should suffice. Cheers, Simon