Fix doc generator for interfaces + some potential improvements

[matteolimberto-da]

trafficstars

I confirm that, if this is a bug that has security implications, I already contacted [email protected] and followed the responsible disclosure policy.

I confirm that this is not a question or a request for technical support by the community, for which the Daml forum is available.

Affected Daml version

2.4.0-snapshot.20220703.10163.0.89b068ec

Bug description

The rst documentation generated for Interface methods by compiler/damlc/daml-doc uses a whitespace before closing the strong emphasis (**).

This violates the rst restrictions and causes an error when building the web docs.

In addition, please find below some suggestions to make interface documentation more user-friendly.

To reproduce

• Define an interface with a method in a Daml project
• generate documentation using daml damlc docs ... like in https://github.com/digital-asset/daml-finance/blob/main/scripts/generate-doc.sh#L18

Expected behavior

Doc generation for interface methods does not error out.

Additional context

Some additional improvements that could make interface docs more user-friendly:

1. avoid generating doc for interface type-classes / instances such as HasToInterface, HasFromInterface or HasImplementation

2. interface methods are currently also duplicated as functions in the documentation, maybe this is not necessary

3. use the interface name instead of type synonyms in implements:

It is common to use a qualified type synonym I for interfaces. For instance:

import Daml.Finance.Interface.Asset.Instrument qualified as Instrument (I)
import Daml.Finance.Interface.Common.Disclosure qualified as Disclosure (I)

template X ...
  implements Disclosure.I ...
  implements Instrument.I ...

In the generated documentation for template X, we see

• implements I
• implements I

instead of

• implements Instrument
• implements Disclosure

which makes it harder to read (as we are forced to click on I to understand what I refers to.