doc: a first stab at adding more JavaDoc