Original bug ID: 6254
Reporter: jtoman
Assigned to: @zoggy
Status: assigned (set by jtoman on 2013-12-01T06:42:07Z)
Resolution: open
Severity: feature
Category: ocamldoc
Tags: patch

Bug description

It would be nice if the Ocamldoc tool automatically generated links to exceptions referenced in doc comments via the @raise tag.

Attached are two patches that contain potential starting points for this feature (both of which have been applied against trunk).

About these patches:
Both add a new option to ocamldoc, -link-raise which will, when possible, generate cross links between exceptions referenced in @raise comments and their definition. If the cross referencing is impossible due to limitations on the output format (or a cross reference wasn't found) the old style comments are generated instead.

The first approach, link_raise_field.patch, adds a new option field to the raised_exception type. A value of "None" for this field indicates no cross-reference was found (or the user did not opt into cross-referencing). A value of "Some path" indicates the reference exception was found and the string path is a fully qualified path which can be used to generate a link. This approach will break any custom generators and required touching more code.

The second approach, link_raise_bc.patch adds a new field, i_linked_exc which is an associative list mapping the exception name in i_raised_exc to it's full path (for linking). The absence of an exception from the link indicates that no cross-reference was found, or that the user did not opt-into the cross-referencing. This approach was more backwards compatible with existing code, hence the name.

File attachments

• link_raise_bc.patch
• link_raise_field.patch