api-lockfile: revise and expand the documentation