Improve Flag documentation either in the ref doc or in JavaDoc

Today the documentation is a bit sparse and people can only guesstimate what flags are doing.
A more detailed explanation + maybe a use case for each would be beneficial

Also the source of the java doc seems to inline most of the doc making hard to read from the source reference.