change form API to return error instead of warning user.

Update the form API so instead of directly warning the user it returns
an error code to the caller allowing the appropriate action to be
taken outside the core. Additionally clean up documentation of this
API.