--auto-abstract is now default

Author: michaliskambi

src/Abstract.asciidoc

@@ -0,0 +1,65 @@
+:doctitle: Abstract Description
+:sectnums:
+:toc: left
+:toclevels: 4
+
+## Introduction
+
+The documentation looks best if each documented identifier has an _"abstract"_, which means just _"a short description"_. This should usually be just one sentence.
+
+Such abstract description is displayed in various overview pages. It's also used in conjunction with the link:SeeAlsoTag[@seealso tag].
+
+It can be provided:
+
+- using the `@abstract` tag
+
+- or (recommended) it will be automatically deduced from the first sentence of the description. This automatic deduction can be turned off using the `--no-auto-abstract` command-line option.
+
+## `@abstract` tag
+
+You can use the `@abstract` tag to explicitly delimit a short explanation of the documented item. There should be at most one `@abstract` tag per description.
+
+Example:
+
+[source,pascal]
+----
+{ @abstract(Read JSON file.)
+  Read the JSON file indicated by the given URL.
+  The resulting JSON object is owned by the caller, and must be freed by the caller. }
+function ReadJson(const Url: string): TJsonValue;
+----
+
+The abstract description provided this way is always separated from the rest of the description by a paragraph break. This is in contrast to the case when the abstract description is deduced automatically from the first sentence of the description (see below), where paragraph break is done only if you explicitly insert an empty line between the first sentence and the rest of the description.
+
+## Automatic determination of abstract description
+
+If no `@abstract` tag is present in the description of an item, we will deduce the abstract description from the first sentence of the full description. Example:
+
+[source,pascal]
+----
+{ Read JSON file.
+  Read the JSON file indicated by the given URL.
+  The resulting JSON object is owned by the caller, and must be freed by the caller. }
+function ReadJson(const Url: string): TJsonValue;
+----
+
+The first sentence is determined by looking for a _first period followed by any whitespace_ (including newline). If there is no such period in the description, then the _whole_ description is treated as one sentence, and the _whole_ description is treated as an abstract description of the item.
+
+We recommend to utilize this automatic deduction of the abstract description. It makes the comments look less cluttered when you don't need to write `@abstract` everywhere.
+
+Write the documentation such that **the first sentence of every description "stands on its own"**.
+
+## Disable automatic deduction of abstract description (`--no-auto-abstract`)
+
+If you really want to, you can disable the automatic deduction of the abstract description by using the `--no-auto-abstract` command-line option. In this case, if no `@abstract` tag is present in the description of an item, then no abstract description will be generated for that item.
+
+## Other software
+
+- This is a standard feature of _JavaDoc_ as well.
+
+- https://www.doxygen.nl/manual/docblocks.html[Doxygen also has a similar feature]. With `JAVADOC_AUTOBRIEF` enabled, the first sentence of the description is used as a brief description, just like with _JavaDoc_ and _PasDoc_. Without `JAVADOC_AUTOBRIEF`, you still don't have to write `\brief` to provide a brief description, as long as you separate first line of the description from the rest of the description with a newline.
+
+## Example unit
+
+See https://github.com/pasdoc/pasdoc/blob/master/tests/testcases/ok_auto_abstract.pas[test unit of this feature].
+

src/AbstractTag.asciidoc

@@ -1,28 +1,3 @@
 :doctitle: @abstract tag
 
-For some item types like classes or units you may write very large
-descriptions to give an adequate introduction. However, these large
-texts are not appropriate in an overview list. Use the abstract tag to
-give a short explanation of what an item is about. One row of text is a
-good rule of thumb. Of course, there should only be one abstract tag per
-description.
-
-Example:
-
-[source,pascal]
-----
-type
-  { @abstract(This class does some very useful thing.)
-    With the help of this class you can ...
-    (more text that describes how very very
-    useful is this class follows). }
-  TMyClass = class ...
-----
-
-The abstract text will appear in the overview section of the
-documentation (if the document format supports this overview section),
-and will also appear as the first paragraph of the item full
-documentation.
-
-Note that can avoid writing explicit @abstract tag if you use
-link:AutoAbstractOption[--auto-abstract command-line option].
+The `@abstract` docs moved to the link:Abstract[Abstract Description] page of the documentation.

src/AdvancedFeatures.asciidoc

@@ -7,7 +7,7 @@ Some important non-obvious PasDoc features:
 
 == Input
 
-* link:AutoAbstractOption[--auto-abstract] command-line option allows you to automatically treat the 1st sentence of the description as an abstract.
+* We automatically treat the 1st sentence of the description as an link:Abstract[abstract]. So make sure it "stands on its own" and is a good short description of the item. You can also explicitly specify the abstract using link:Abstract[@abstract tag].
 
 * You can write entire pages using pasdoc syntax, with all supported link:SupportedTags[@tags]. This way you can use pasdoc like a simple document creation tool. See the link:IntroductionAndConclusion[Introduction and conclusion] documentation.
 

src/AutoAbstractOption.asciidoc

@@ -1,77 +1,3 @@
 :doctitle: --auto-abstract command-line option
 
-## [[overview]] Overview
-
-If you run pasdoc with --auto-abstract link:CommandLine[CommandLine]
-option, pasdoc will automatically deduce the abstract description of
-every item from the first sentence of it's description. This means that
-you can write
-
-[source,pascal]
-----
-type
-  { Short description of this class.
-    More elaborate description of this class. }
-  TMyClass = class
-----
-
-and it's equivalent to
-
-[source,pascal]
-----
-type
-  { @abstract(Short description of this class.)
-    More elaborate description of this class. }
-  TMyClass = class
-----
-
-This means that you can avoid writing explicitly @abstract tags, which
-means that your comments look less cluttered. Of course, this also means
-that you have to carefully watch to make the first sentence of every
-description to "stand on it's own".
-
-This is a standard feature of javadoc, and it's also available in
-doxygen.
-
-The parsing logic is simple: the first sentence of the description ends
-at the first period followed by any whitespace (including newline). Of
-course this period must be in the "top-level" text, not inside parameter
-of any @-tag. If there is no such period in the description, then the
-_whole_ description is treated as one sentence, and the _whole_
-description is treated as an abstract description of the item.
-
-Of course if any description has an explicit @abstract section, then
-this has priority over "the first sentence rule". Using explicit
-@abstract tag may be useful if e.g. you need to make the abstract
-description two-sentence long.
-
-## [[small-difference-between-explicit-abstract]] Small difference between explicit @abstract
-
-Note that there is actually a small difference between two examples
-given above. It occurs when pasdoc writes full description of a given
-item (full = abstract one + the rest).
-
-If you used explicit @abstract tag, then pasdoc will always separate the
-abstract description with some space (e.g. paragraph marker, <p>, in
-HTML) from the rest of the description. But if your abstract description
-was deduced automatically, then pasdoc will not automatically insert
-such paragraph. This way full description of an item looks more like it
-was specified in source code.
-
-So if I would really want to make two exactly equivalent examples, I
-should show this as the first example (note that I explicitly inserted
-empty line between abstract description and the rest here):
-
-[source,pascal]
-----
-type
-  { Short description of this class.
-
-    More elaborate description of this class. }
-  TMyClass = class
-  ...
-----
-
-## [[example-unit]] Example unit
-
-See https://github.com/pasdoc/pasdoc/blob/master/tests/testcases/ok_auto_abstract.pas[test unit of this feature].
+The `--auto-abstract` docs moved to the link:Abstract[Abstract Description] page of the documentation.

src/CommandLine.asciidoc

@@ -123,8 +123,8 @@ How multipart links (like @link(Unit.Procedure)) look like in output
 link:LinkLookOption[--full-link]::
 Obsolete name for --link-look=full option.
 
-link:AutoAbstractOption[--auto-abstract]::
-Automatically deduce @abstract description of item from 1st sentence of it's full description
+link:Abstract[--auto-abstract]::
+Deprecated. This is the default now.
 
 link:CssOption[--css, --css-based-on-bootstrap]::
 Use the code of your cascading style sheet in replacement of default one.
@@ -150,6 +150,9 @@ Specify the name of a text file that should be inserted into the preamble of a L
 link:ImplicitVisibilityOption[--implicit-visibility]::
 How pasdoc should handle class members within default class visibility.
 
+link:Abstract[--no-auto-abstract]::
+Disable automatic deduction of abstract description from the first sentence of the full description.
+
 link:NoMacroOption[--no-macro]::
 Turn FPC macro support off.
 

src/SeeAlsoTag.asciidoc

@@ -13,8 +13,7 @@ multiple items that are related to this item.
 
 In output documentation, this will result in "See also" section created
 in description of this item. This section will list all items specified
-by @seealso tags. Abstract descriptions (the one created e.g. by
-link:AbstractTag[@abstract tag]) of each related item will also be
+by @seealso tags. link:Abstract[Abstract description] of each related item will also be
 shown.
 
 ## [[simple-example]] Simple example

src/SupportedTags.asciidoc

@@ -10,7 +10,7 @@ others do not, see link:TagsParameters[TagsParameters].
 Alphabetical list of supported tags:
 
 @@:: Insert the @ character literally
-link:AbstractTag[@abstract]:: Specify a short abstract of the description
+link:Abstract[@abstract]:: Specify a short abstract of the description
 link:IntroductionAndConclusion[@anchor]:: Set up an invisible anchor inside introduction/conclusion
 link:AuthorTag[@author]:: Specify an author's name (and email address etc.)
 link:BoldAndItalicTags[@bold]:: Format text using bold font

src/WhereToPlaceComments.asciidoc

@@ -1,4 +1,7 @@
 :doctitle: Where To Place Comments
+:sectnums:
+:toc: left
+:toclevels: 4
 
 ## [[basic-rule]] Basic rule
 

src/WritingDocumentation.asciidoc

@@ -1,4 +1,9 @@
 :doctitle: Writing Documentation Comments
+:sectnums:
+:toc: left
+:toclevels: 4
+
+## Introduction
 
 PasDoc extracts documentation from the comments that you place in your
 source code (and from external files if you use the
@@ -8,6 +13,10 @@ See link:WhereToPlaceComments[WhereToPlaceComments] for more explanation
 *where* to place comments. This page describes special syntax *features
 available in documentation comments*.
 
+## First sentence should stand on its own
+
+The first sentence of every documentation comment is the most important. It determines the link:Abstract[abstract (short) description] of this item, which is shown in various overviews, and as such should "stand on its own". Make it a short and precise sentence that describes the item.
+
 ## [[expanding-tags]] Expanding @-tags
 
 See link:SupportedTags[SupportedTags].

src/_Sidebar.asciidoc

@@ -15,7 +15,7 @@ Features: ::
 
 
 link:SupportedTags[Supported Tags]: ::
-* link:AbstractTag[@abstract]
+* link:Abstract[@abstract]
 * link:AuthorTag[@author]
 * link:BoldAndItalicTags[@bold, @italic]
 * link:BrTag[@br]
@@ -55,7 +55,7 @@ link:CommandLine[Command Line]: ::
 ** link:LatexOutput[--format=latex]
 ** link:Latex2RtfOutput[--format=latex2rtf]
 ** link:SimpleXmlOutput[--format=simplexml]
-* link:AutoAbstractOption[--auto-abstract]
+* link:Abstract[--auto-abstract]
 * link:AutoBackComments[--auto-back-comments]
 * link:AutoLinkOption[--auto-link, --auto-link-exclude]
 * link:CacheOption[--cache]
@@ -80,6 +80,7 @@ link:CommandLine[Command Line]: ::
 * link:LinkLookOption[--link-look]
 * link:MarkdownOption[--markdown]
 * link:NameOption[--name]
+* link:Abstract[--no-auto-abstract]
 * link:NoMacroOption[--no-macro]
 * link:OutputLanguage[--language]
 * link:OutputOption[--output]