odoc .mld file, @see tags, can't separate from the rest of the document

[tomjridge]

I have a .mld file which contains:

{0 Sparse-file package}

{1 Previous documents}

@see <https://github.com/tomjridge/public_notes/blob/master/2022-01-11_tjr_irmin_gc.pdf> "Implementing GC for Irmin", describes the basic structure of a pack file, what a sparse file is, etc

@see <https://github.com/ngoguey42/irmin/blob/rfc-obls/offset_based_layered_store.md> "Offset-based layered store", proposal by [@ngoguey]

@see <https://docs.google.com/presentation/d/e/2PACX-1vR6C-haCfJcosL7dz-QvjStSazjiKyz0aRCpcqImU10yNgVm0Fbu4pvfx2HaP4pJ2ENbgLuBquEm3Nq/pub?start=false&loop=false&delayms=3000> Slides to present the proposal

@see <https://github.com/tomjridge/sparse-file> An implementation of a sparse file, suffix file, worker process, irmin simulation


{1 Overview}

The problem is that the last @see gives a warning:

File "../../../../src/index.mld", line 14, characters 0-2: '{1 ...}' (section heading) is not allowed in '@see'.`

Because parsing the tag presumably runs on to include the {1 Overview} heading. I guess in normal OCaml comments, the tags are last, and so the processing ends with the end of comment *). In a .mld there is no end of comment, so parsing is maybe more complicated?

[tomjridge]

Ignore this. @see tags have to come at the end of a .mld

[Julow]

Tags in general have to come at the end of a comment. But a .mld is not really a comment, the rules should be different.

We could:

• Allow some tags in mlds
• Allow some tags to be anywhere in a comment
• Entirely disallow tags in mlds

Also, there's a problem with the parsing of @see tags in your example. It says that the heading at the end of the example is not allowed in the rhs of the @see tag. This does not look like a good parsing rule to me.

[dbuenzli]

• Entirely disallow tags in mlds

I would rather be in favour of that, and deprecate tags in general, everywhere. They don't really bring any benefit, doc strings should be for humans not for machines.

The only ones that are remotely useful are @raise, @since and @before but in fact it would be much more beneficial to have these as attributes (like [@@ocaml.deprecated]), so that they can easily be acted upon by tooling.

At some point I thought that @deprecated tags were lifted into [@@ocaml.deprecated …] attributes or vice-versa. But it seems I dreamt that, see #406.

{1 Previous documents}

@tomjridge this could be easily replaced by an unordered list and the regular linking syntax.

[Julow]

I think even humans like to have standard rendering for some kind of data. I wouldn't rely on a human sentence for things like "since" and "deprecated" data but I agree attributes would be better than tags for that purpose (but quite heavier on syntax).

Btw, Odoc should definitely pick the deprecated attribute and render it like the @deprecated tag, which is not rendered at the moment. Same for all attributes.

[dbuenzli]

I think even humans like to have standard rendering for some kind of data.

Yes sure for @since, @deprecated and co it all makes sense. But these should definitively be lifted from alerts or attributes (and the alert string be interpreted in the ocamldoc language) to be concatenated at the end of the doc string – currently you have to repeat yourself which is horrible.

I was more talking about the @param and @returns for which the documentation style of the stdlib is a better idea, as it tells you how to read an application's value in human terms (and simply use a list if you have too many arguments).

In any case with respect to @tags in .mld files this should be related to https://github.com/ocaml/odoc/issues/575. In particular reading this section one can interpret that @tags only apply to (certain) elements (defined in the third paragraph here as being structure items) and are otherwise ignored.

Since there are no elements in .mld files @tags should simply be ignored in these.

[jonludlam]

AIUI the problem with @see are that it's a 'block tag' that contains further markup. The issue is that there's no 'end' to the text that's associated with the tag - so we rely either on the next tag or end of comment to terminate it.

In general I completely agree that pushing some of the tags down into attributes is sensible, then tools wanting to consume them only need the ocaml parser not the odoc parser too. I also think this is a good way to distinguish between things that should remain machine readable and those that should just be turned into markup - would it be useful for more than just odoc to know about these bits of metadata? e.g. see fails this test.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.