improved documentation of main methods