The NatSpec documentation is now published and officially supported in the compiler documentation.
For Solidity see: https://solidity.readthedocs.io/en/develop/natspec-format.html
For Vyper see: https://vyper.readthedocs.io/en/latest/structure-of-a-contract.html#natspec-metadata