inline documentations for optioning
enhances documentation on readme and inline on deprecation