ANN: Updating flag description in the User's Guide

[Simon Marlow]

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