harmonization of some docs with code fragments