Currently we only have a very brief explanation on the unexpected error
handling (only ASSERT()/WARN_ON()/BUG_ON()), and no further
recommendation on the proper usage of them.
This patch would improve the guideline by:
- Add btrfs_abort_transaction() usage
Which is the recommended way when possible.
- More detailed explanation on the usage of ASSERT()
Which is only a fail-fast option mostly designed for developers, thus
is only recommended to rule out some invalid function usage.
- More detailed explanation on the usage of WARN_ON()
Mostly for call sites which need a call trace strongly, and is not
applicable for a btrfs_abort_transaction() call.
- Completely discourage the usage of BUG_ON()
Signed-off-by: Qu Wenruo <wqu@suse.com>
Signed-off-by: David Sterba <dsterba@suse.com>
- use :file: and :command:
- simplify manual page references
- add more web links
- typo fixes
- more cross-references
Signed-off-by: David Sterba <dsterba@suse.com>
