Documentation fragments and comments in OpenQL source could be improved

[jvansomeren]

In general, we'd like header files of classes to contain only comment that is functional (implementation independent),
and implementation files of classes explain the various implementation options/choices.
Note that header file comment is also used by doxygen.
Documentation fragments are used to compose the readthedocs documentation and should thus be functional;
this can be improved, partially by simplifying the interfaces of course (not this issue), and otherwise by being more clear on the various cases, models, constraints, etc. An example is the meaning of options; perhaps some should be taken out of the readthedocs fragments because they are too much implementation related.

For this issue, first the documentation fragments, then the header file comment and then the implementation file comments are revised.