DOC: make api docs reflect api usage (#4539)