Support references in code spans

[MisterDA]

I noticed that the Lwt documentation has doc comments like this:

There are straightforward ways to make promises canceled. One could create a
promise that {e starts out} canceled, with {!Lwt.fail}[ Lwt.Canceled]. It's
also possible to {e make} a promise canceled through its resolver, by
calling {!Lwt.wakeup_later_exn}[ r Lwt.Canceled].

The intent is to have a little code example with a reference to the
function used. The output however isn't very nice:

<p>There are straightforward ways to make promises canceled. One
could create a promise that <em>starts out</em> canceled, with
<a href="index.html#val-fail"><code>Lwt.fail</code></a><code>Lwt.Canceled</code>.
It's also possible to <em>make</em> a promise canceled through its resolver, by calling
<a href="index.html#val-wakeup_later_exn"><code>Lwt.wakeup_later_exn</code></a>
<code>r Lwt.Canceled</code>.</p>

It would be much nicer to merge the consecutive <code> tags, and to
be able to embed references in these short code blocks. Depending on
the document format or the CSS, it can get very ugly. Is there a way
to achieve that? If not, could odoc add support for it?

They also write this, and the result looks very weird imo:

If [f] raises an exception, it is passed to [!]{!Lwt.async_exception_hook}.
By default, this will terminate the process. *)

Thanks.

[panglesd]

This could be achieved (in code spans, not code blocks) by having a {c ...} (c for codespan) which renders as a codespan but contains odoc inline elements instead of plain text.

[favonia]

@panglesd This is a great idea! Personally I prefer {code ...} over {c ...} for several reasons: (1) for me it is easier to remember and (2) it matches the HTML tag <code>, just like {ul/ol/i/b... ...} and (3) we can still add {c ...} later on.