Clarify some of the docs

Author: BarkingBad

docs/docs/usage/scaladoc/settings.md

@@ -144,12 +144,12 @@ Example JSON file:
 
 ##### -snippet-compiler
 
-Snippet compiler arguments provide a way to configure snippet checking.
+Snippet compiler arguments provide a way to configure snippet type checking.
 
 This setting accepts a list of arguments in the format:
 args := arg{,arg}
 arg := [path=]flag
-where the path is a prefix of source paths to members to which argument should be set.
+where `path` is a prefix of the path to source files where snippets are located and `flag` is the mode in which snippets will be type checked.
 
 If the path is not present, the argument will be used as the default for all unmatched paths.
 
@@ -176,4 +176,5 @@ Setting this option makes snippet compiler print the snippet as it is compiled (
 
 ##### -Ydocument-synthetic-types
 
-Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib
+Include pages providing documentation for the intrinsic types (e. g. Any, Nothing) to the docs. The setting is useful only for stdlib because scaladoc for Scala 3 relies on TASTy files, but we cannot provide them for intrinsic types since they are embedded in the compiler.
+All other users should not concern with this setting.

docs/docs/usage/scaladoc/staticSite.md

@@ -29,7 +29,7 @@ index.html
 docs/getting-started.html
 ```
 
-Scaladoc can transform both files and directories (to organize your documentation into a tree-like structure). By default, directories have a title based on the file name and have empty content. There is an option to include `index.html` or `index.md` (not both) to provide both content and properties like the title (see [Properties](#properties)).
+Scaladoc can transform both files and directories (to organize your documentation into a tree-like structure). By default, directories have a title based on the file name and have empty content. It is possible to provide index pages for each section by creating `index.html` or `index.md` (not both) in the dedicated directory.
 
 ## Properties
 
@@ -156,7 +156,7 @@ In `subsection`s, you can omit `title` or `index`, however not specifying any of
 
 ## Hierarchy of title
 
-If the title is specified multiple times, the priority is as follows (from highest to lowest priority): 
+If the title is specified multiple times, the priority is as follows (from highest to lowest priority):
 
 #### Page
 

scaladoc/src/dotty/tools/scaladoc/ScaladocSettings.scala

@@ -103,7 +103,7 @@ class ScaladocSettings extends SettingGroup with AllScalaSettings:
   )
 
   val YdocumentSyntheticTypes: Setting[Boolean] =
-    BooleanSetting("-Ydocument-synthetic-types", "Documents intrinsic types e. g. Any, Nothing. Setting is useful only for stdlib", false)
+    BooleanSetting("-Ydocument-synthetic-types", "Attach pages with documentation of the intrinsic types e. g. Any, Nothing to the docs. Setting is useful only for stdlib.", false)
 
   val snippetCompiler: Setting[List[String]] =
     MultiStringSetting("-snippet-compiler", "snippet-compiler", snippets.SnippetCompilerArgs.usage)

scaladoc/src/dotty/tools/scaladoc/snippets/SnippetCompilerArgs.scala

@@ -30,14 +30,14 @@ case class SnippetCompilerArgs(scFlags: PathBased[SCFlags], val debug: Boolean,
 object SnippetCompilerArgs:
   val usage =
     """
-    |Snippet compiler arguments provide a way to configure snippet checking.
+    |Snippet compiler arguments provide a way to configure snippet type checking.
     |
     |This setting accept list of arguments in format:
     |args := arg{,arg}
     |arg := [path=]flag
-    |where path is a prefix of source paths to members to which argument should be set.
+    |where `path` is a prefix of the path to source files where snippets are located and `flag` is the mode in which snippets will be type checked.
     |
-    |If path is not present, argument will be used as default.
+    |If the path is not present, the argument will be used as the default for all unmatched paths..
     |
     |Available flags:
     |compile - Enables snippet checking.