Implicitly ended tags.

CHANGES.md

@@ -49,6 +49,7 @@
   `{delim@lang[ code ]delim[ result ]}`
 - Output file paths and labels in the man and latex backends changed to avoid name clashes
   (@Julow, #1191)
+- Change the scoping and placement rules for tags. Fixed #1138. (@panglesd, #1239)
 
 ### Fixed
 

doc/ocamldoc_differences.mld

@@ -15,6 +15,7 @@ The following describes the changes between what [odoc] understands and what’s
 - Heading levels are more restrictive. In the manual, it suggests any whole number is acceptable. In [odoc],
   similarly to the HTML spec, we allow headings from 1-5. Heading level [0] is for the title
   of [.mld] files. [odoc] emits a warning for heading levels outside this range and caps them.
+- Tags are restricted in scope and do not need to be put at the end of the docstring.
 
 {3 Omissions}
 - Comments describing class inheritance are not rendered ({{:https://github.com/ocaml/odoc/issues/574}GitHub issue}).

doc/odoc_for_authors.mld

@@ -485,8 +485,7 @@ the {{!page-driver}driver}.
 {2:tags Tags}
 
 Tags are used to provide specific information for individual elements, such
-as author, version, parameters, etc. Tags start with an [@] symbol, appear
-at the end of documentation comments, and are not allowed elsewhere.
+as author, version, parameters, etc. Tags start with an [@] symbol.
 They should appear on their own lines with nothing but whitespace before them.
 
 There are three types of tags. Those with:
@@ -522,8 +521,8 @@ i.e., there shouldn't be any [odoc] markup.
 {3 Block Tags}
 
 These tags have a block of potentially marked-up text associated with them,
-and occasionally some more data too. The block of text concludes with the end
-of the comment or by another tag. They are:
+and occasionally some more data too. The block of text is implicitly ended by a
+new line, a heading or another tag.
 
 - [@deprecated <text>] - marks the element as deprecated. [text] should describe
 when the element was deprecated, what to use as a replacement, and possibly