updating doc acording to latest refactorings, minor enhancings