add new methods' documentation
fix typo
apply Jas' review