4 - document the semantics