@-tags include everything after them #1138

lpw25 · 2024-05-31T12:39:58Z

I'm pretty sure I implemented this behaviour once upon a time and I did so to match ocamldoc's existing behaviour. But I wonder if it is a mistake to have @tags extend onwards until either the end of the comment or another @tag. I just found something like:

(** Some docs about things

     @param foo Stuff about a parameter
     
     More stuff about the whole function, not just the parameter. *)

and it seems a very reasonable thing to write, but it gets rendered very badly because everything after @param is considered part of the tag. (Also #329 is right, the markup for tags is bad).

Perhaps we should take a blank line as ending the tag? I think the actual tags we support would be fine only taking a single paragraph as input.

The text was updated successfully, but these errors were encountered:

jonludlam · 2024-10-17T16:12:53Z

I think it's useful to see the existing bits of code that might be affected by this change. I did a very naive run of the docs ci on the latest version of every package with some very basic instrumentation to detect more than one nestable-block-elements in these tags. It's a bit tricky to get things exact, but it's a good representative set. The output is here: https://gist.github.com/jonludlam/e099db11eb65404e502948056450d54c

jonludlam · 2024-10-21T08:49:34Z

I went through those examples of the affected code, though not exhaustively -- there are a lot! I did find instances where the change would not be good, but I also found many more where the change would make the docs better. So I'm in favour of the suggestion of having a blank line end the tag. We might also want to consider other ways to end it, like a heading? I wouldn't suggest all block markup as there are some instances in the above of e.g. lists being used sensibly in @param and @return tags.

dbuenzli · 2024-10-21T15:14:04Z

I wouldn't suggest all block markup as there are some instances in the above of e.g. lists being used sensibly in @param and @return tags.

I think it should be all blocks but introduce a way for making multiple blocks if you saw it needed.

I can see two possibilities here:

Having a way to escape blank lines, I suggested @ here.
Having proper delimiters as a suggested by @EmileTrotignon here. But I think it would be better to have it as @ directives rather than overloading or inventing new brackets. E.g. @tag @begin-blocks … @end-blocks.

Solution 2. looks cleaner to me.

panglesd · 2024-10-29T15:54:38Z

I've tried to use a bit @jonludlam's experiment to understand more what would be fixed/broken depending on our choice of syntax.

I tried to open at least one link per package in Jon's list, and to classify them¹. The classification is two-dimensional: what is the second item in the @-block, and whether the author expected it to have split the block.

In case that is not clear, open this for examples on how I categorized the entries.

  @param foo The number of things

  The function runs in linear time

is in "New line", "Should break" ; while

  @param foo When foo is:
    - [true] then bli
    - [false] then blu

is in "List", "Should not break".

In case it needs disambiguation:

  @param foo When foo is:

    - [true] then bli
    - [false] then blu

is in "New line", "Should not break".

There are also several results that were included in @jonludlam's list due to an incorrect use of odoc's syntax. I'll open separate issues for those that are worth it.

Another thing I spot is that authors often use indentation with tags, when they mean to put it all in the tag block. But odoc can't rely on that...

Let's enumerate the possibilities we have (I'm not speaking about the way we would define a delimiter for @-blocks yet).

Say that any new block item ends the @-block
It is good for the 59 "New line"/"Should break" entries.
This has the advantage of being the least surprising.
Say that a blank line ends the @-block.
It is good for the 59 "New line"/"Should break" entries and the 9 entries in "List"/"Should not break".
Not too surprising, but a little bit more.
Say that only a new paragraph ends an @-block (of course, unless delimited by the to be decided syntax).
It is good for the 59 "New line"/"Should break" entries and the 9 entries in "List"/"Should not break", and about half of the 9 entries in "New line"/"Should not break" (since those are often not followed by a new paragraph but by a new list / code block).
The most backward compatible, but quite surprising rule...

I would prefer the solution 1, even though it is the least backward compatible. But I would be fine with solution 2.

By hand, that was very boring! ↩

jonludlam · 2024-10-30T11:47:43Z

Thanks for going through the list, that was a lot of work!

I'm fine with either options 1 or 2, though I lean ever so slightly in favour of 2 rather than 1.

dbuenzli · 2024-10-30T12:30:56Z

I'd be more in favour of 1. Unless I'm mistaken in the current language:

{ul …}
{| …|}

and

{ul …}

{|…|}

are strictly equivalent. If we adopt 2. that would no longer be the case in @-tag contexts. I don't find this to be a desirable property.

panglesd · 2024-11-05T15:08:33Z

I have investigated, and finally found something that add grist to my mill!

Ocamlformat (with the --parse-docstring option, which is now on by default) often makes a difference between blocks separated by a new line, and those that are not separated by a new line, in the sense that it preserves it:

Paragraph directly followed by a code block
{[ blibli ]}

Paragraph with a line before the code block

{[ bloblo ]}

Becomes

Paragraph directly followed by a code block
{[
  blibli
]}

Paragraph with a line before the code block

{[
  bloblo
]}

However, it assumes that it is safe to add newlines between lists when needed:

{ul
  {- First item}
  {- Second item}
  {li can also be used}}
{ol
  {- First numbered item}
  {- Second numbered item}
  {li can also be used}}

is formatted as

- First item
- Second item
- can also be used

+ First numbered item
+ Second numbered item
+ can also be used

So, ocamlformat assumed it is safe to add a newline (and it was). Going with option 2., ocamlformat would change the meaning of the docstring when formatting.

This is not a discriminating reason to chose 2. over 1., but that's comforting me in my preference for 1.

panglesd · 2024-11-07T08:38:43Z

We discussed this during the dev meeting and decided to go for 1:

Any new block ends the @ block!

I'll start implementing this soon.

panglesd · 2024-11-08T08:00:54Z

While implementing this, I was surprised by how the implicit ending of list light syntax work.

So, blank lines, section headings, closing bracket and tags end a list item:

- A list item
{1 Title not part of the list item}

However, other blocks (eg code blocks, media blocks, ...) do not end the list item:

- A list item
{[A code block, part of the list item]}

A quick search shows that this is indeed used in the wild.

If we implement the tag as planned (takes a single block, without constraint), this creates some strange interaction.

For instance:

@tag
  This is part of the tag
  {[this code block is not]}

@tag
  - This is part of the tag
  {[so is this code block, as part of the first list item]}

This inconsistency is problematic. It seems to make sense to have the same rule for implicit ending of both tags and light syntax list.

They are not necessarily at the end anymore, and the end similarly as light syntax list: on new lines or heading. This is a breaking change, which according to ocaml#1138 is fixing more things than breaking them. It will allow using custom tags and tags in mld files.

jonludlam · 2024-11-13T13:24:40Z

I'm quite happy with being consistent with the way lists are terminated, that's one less thing to have to remember. Having said that I think we'll still need to have a way to have multi-paragraph tags (and lists, for that matter), so issue #1226 is still important.

They are not necessarily at the end anymore, and the end similarly as light syntax list: on new lines or heading. This is a breaking change, which according to #1138 is fixing more things than breaking them. It will allow using custom tags and tags in mld files.

They are not necessarily at the end anymore, and the end similarly as light syntax list: on new lines or heading. This is a breaking change, which according to ocaml#1138 is fixing more things than breaking them. It will allow using custom tags and tags in mld files.

sabine mentioned this issue Sep 26, 2024

UI: Fix rendering of tags #1198

Open

panglesd mentioned this issue Oct 15, 2024

Frontmatter syntax #1210

Closed

This was referenced Oct 29, 2024

Doc comments with * at the beginning of each lines. #1224

Open

@-tags delimiter #1226

Open

panglesd mentioned this issue Nov 8, 2024

Implicitly ended tags. #1239

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

@-tags include everything after them #1138

@-tags include everything after them #1138

lpw25 commented May 31, 2024

jonludlam commented Oct 17, 2024 •

edited

Loading

jonludlam commented Oct 21, 2024

dbuenzli commented Oct 21, 2024 •

edited

Loading

panglesd commented Oct 29, 2024

jonludlam commented Oct 30, 2024

dbuenzli commented Oct 30, 2024

panglesd commented Nov 5, 2024

panglesd commented Nov 7, 2024

panglesd commented Nov 8, 2024

jonludlam commented Nov 13, 2024

@-tags include everything after them #1138

@-tags include everything after them #1138

Comments

lpw25 commented May 31, 2024

jonludlam commented Oct 17, 2024 • edited Loading

jonludlam commented Oct 21, 2024

dbuenzli commented Oct 21, 2024 • edited Loading

panglesd commented Oct 29, 2024

Newline

Lists

Code blocks

Footnotes

jonludlam commented Oct 30, 2024

dbuenzli commented Oct 30, 2024

panglesd commented Nov 5, 2024

panglesd commented Nov 7, 2024

panglesd commented Nov 8, 2024

jonludlam commented Nov 13, 2024

jonludlam commented Oct 17, 2024 •

edited

Loading

dbuenzli commented Oct 21, 2024 •

edited

Loading