Improve domain validation error to be more human readable

Rational

Domains are awesome. They allow to manage data integrity in a very straightforward way.
Actually the framework is able to show a descriptive validation error message for simpler domains. Otherwise a generic message is shown.
Indeed with the generic error the user rarely knows what is wrong. From deployer side is also difficult to determine it when either the domain is very complex or it has got many clauses or it’s extended in several modules.

Proposal

Add a new optional parameter “domain_help” in fields in order to define human readable text for each condition. It would be a list and the elements should be in same order than clauses in domain.
The error message will show the text of the invalid condition or all domain help if defined (I’m afraid domain is validated as a whole).
Opinions?

Implementation

For me, it sounds like an ad-hoc solution. I see many potential issues with this:

  • the text will not be kept up to date (wrong information instead of none, which is worst)
  • the text will be difficult to extend when the domain is extended. Natural languages are not as composable as a domain is.
  • domain may be too complex to express in a sentence.

For me, it is better to work on improving the DomainParser to be able to stringify more domains.
And also to implement it on the server side to allow server to provide better error message also.

That’s a well known problem with documentation.

That will be a great solution (I thought there wasn’t anything more to do at this point).