@damiendoligez do we really need to delay this to after the release? The actual typos look like they could be merged before that. (It's not much but it could help people looking at the flambda code at release time.)

The one thing I would be concerned with is the changes turning some comments into documentation comments. Now that the compiler parses comments, this introduces a risk of trouble. I would ask @Fourchaux to forget about this part of the PR.

The one thing I would be concerned with is the changes turning some comments into documentation comments. Now that the compiler parses comments, this introduces a risk of trouble. I would ask @Fourchaux to forget about this part of the PR.

Can you elaborate?
It might cause problems when one enables warning 50 on the compiler, but do you have something else in mind?

As for warning 50, this change in particular will probably trigger it (as the parser won't know whether to attach the doc to the field on the line before or on the line after). Then again the same ambiguity is already present with the comment 2 lines above (which wasn't touched by @Fourchaux ).
Note that this is the only change from regular comment to documentation comment which is problematic in this PR I believe.

Personally I wouldn't ask him to revert that part of the changes, but I would ask him to do more such changes :) Although that can be done in a separate PR (not named "typos").

(as the parser won't know whether to attach the doc to the field on the line before or on the line after)

Actually that one is fine. With fields comments have to come after the field so there is no ambiguity. I'm fairly sure I turned on warning 50 for the compiler to make sure people didn't add any ambiguities, but it's possible I'm misremembering.

With fields comments have to come after the field so there is no ambiguity.

Good to know.
Of course this is not what is done on the record definition I linked, where the comments actually come before the field. :)

Of course this is not what is done on the record definition I linked, where the comments actually come before the field. :)

Hmm. Time for another PR.

@gasche yes I was nervous about the changes from non-doc to doc (and vice-versa). I don't think it's worth the trouble of tinkering with the PR, though. Let's just merge it after branching 4.03.

gasche : "The one thing I would be concerned with is the changes turning some comments into documentation comments.Now that the compiler parses comments, this introduces a risk of trouble."
Well here are my justifications :

• Many files EXCEPT 3 are written with : [@@@ocaml.warning ... (** blabla
  hence the 3 changes of compilation_unit.mli, export_id.mli & middle_end.mli
• For inline_and_simplify_aux.mli (L84) there is a doc comment just above (L71) and an another just below (L88) . Idem for simple_value_approx.mli (L160) with a doc comment L157.
• Concerning closure_id.mli : here I suppress a *, but hey, displaying internal discussion in the documentation could also be interesting.

It was just a few comments (with one *) to say that the "risk of trouble" seems negligible.
Anyway, Flambda (and Ephemerons...) are tremendous, thank you all.

@Fourchaux Thanks for the PR, it is appreciated.

My point was that I can merge a patch which only fixes english typos with my eyes closed (the only exception would be if during the week of RC/testing just before a release, where we avoid changing anything). It is not the case for patches that change documentation comments, as there are more things that could go wrong and I need to think. So, I think that both kind of changes are excellent ideas but, for the next time, I think it is best to separate them.

Okay. Noted.
But see how the Life is Beautiful:
closure_id.mli : on the SAME line L19 we have an english typo AND a wrong doc comment.
Intéressant non ?

@Fourchaux , could you rebase this branch against the current trunk? It could be merged then.

Also please remove spurious .directory files added by the commit.

This PR (being superseded by the updated and -already- merged PR#614 ) can be closed I think.
The discussion about the use of some (* - (** is however still open.
See my note and the comment of @mshinwell in the same PR#614.