Reference documentation in error reports
|Status:||In Progress||Start date:||04/13/2014|
It would be nice to refer users to suitable documentation when certain errors are encountered.
This has been suggested before (see #967).
There are examples in other middlewares:
6.210 [ Warning][DeploymentComponent::configureComponents] The protocol with id 3 did not register a fall-back handler for unknown types! 6.210 [ Warning][DeploymentComponent::configureComponents] triggered by: unknown_t which does not have a transport. 6.210 [ ERROR ][DeploymentComponent::configureComponents] Could not create transport stream for port FRIState with transport id 3 6.210 [ ERROR ][DeploymentComponent::configureComponents] No such transport registered. Check your policy.transport settings or add the transport for type /tFriIntfState
A more generic approach than the above would be attaching references as data structures to exceptions. The information could then be printed in way suiting the situation at hand. Here is an example of such a feature being implemented as a mixin class for exception classes:
The bounding indices 1 and 2 are bad for a sequence of length 0. [Condition of type SB-KERNEL:BOUNDING-INDICES-BAD-ERROR] See also: Common Lisp Hyperspec, _bounding index designator_ [:glossary] Common Lisp Hyperspec, _SUBSEQ-OUT-OF-BOUNDS:IS-AN-ERROR_ [:issue]
_..._parts are hyperlinks. Where could this be used?
- Incompatible payload type vs. informer type => "polymorphic informer" (source:rsb-manual|troubleshooting.rst@20f6d6bc#L215)
- troubleshooting.rst: new file; contains troubleshooting; added link
targets to individual issues
- preparation.rst: removed troubleshooting section
- index.rst: include file troubleshooting.rst
- _static/troubleshooting.svg: new file; icon for troubleshooting
- _templates/page.html: added link to troubleshooting
- troubleshooting.rst: added "Missing Converters" issue
#3 Updated by J. Moringen about 8 years ago
- Status changed from New to In Progress
- % Done changed from 0 to 20
My prototype implementation produces this when no suitable converter can be found:
The domain object :BLA could not be converted to a wire-type :UNDETERMINED representation using the wire-schema :UNDETERMINED Caused by: > No converter could handle the domain-object :BLA. Tried FUNDAMENTAL-VOID, > FUNDAMENTAL-BOOL, > FUNDAMENTAL-INT64, > FUNDAMENTAL-UINT32, > FUNDAMENTAL-INT32, > FUNDAMENTAL-UINT64, > FUNDAMENTAL-DOUBLE, > FUNDAMENTAL-FLOAT, > FUNDAMENTAL-UTF-8-STRING, > FUNDAMENTAL-BYTES, > PROTOCOL-BUFFER See also: RSB/MANUAL, Troubleshooting <http://docs.cor-lab.org/rsb-manual/trunk/html/troubleshooting.html> RSB/PROJECT, Report a bug <https://code.cor-lab.org/projects/rsb/issues/new> RSB/MANUAL, Troubleshooting » Missing Converters <http://docs.cor-lab.org/rsb-manual/trunk/html/troubleshooting.html#missing-converters> RSB/GLOSSARY, converter <http://docs.cor-lab.org/rsb-manual/trunk/html/glossary.html#term-converter>
Note the documentation references at the end of the error message.