You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs/usage/scaladoc/scaladocDocstrings.md
+18-13Lines changed: 18 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ title: Scaladoc docstrings - specific Tags and Features
4
4
5
5
# {{page.title}}
6
6
7
-
This chapater describes how to write correctly docstrings and how to use all available features of scaladoc.
7
+
This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc.
8
8
Since many things are the same as in the old scaladoc, some parts are reused from this [article](https://docs.scala-lang.org/overviews/scaladoc/for-library-authors.html)
9
9
10
10
@@ -13,7 +13,7 @@ to API definitions. This can be used from within static documentation and blog
13
13
posts to provide blend-in content.
14
14
15
15
16
-
## Where to put scaladoc
16
+
## Where to put docstrings
17
17
18
18
Scaladoc comments go before the items they pertain to in a special comment block that starts with a /** and ends with a */, like this:
19
19
@@ -29,8 +29,12 @@ Scaladoc comments go before the items they pertain to in a special comment block
29
29
* left margin is on the same column on the
30
30
* first line and on subsequent ones.
31
31
*
32
-
* The closing Scaladoc tag goes on its own,
33
-
* separate line. E.g.
32
+
* Close the comment with *\/
33
+
*
34
+
* If you use Scaladoc tags (@param, @group, etc.),
35
+
* remember to put them at separate lines with nothing preceding.
36
+
*
37
+
* For example:
34
38
*
35
39
* Calculate the square of the given number
36
40
*
@@ -69,7 +73,7 @@ Scaladoc uses `@<tagname>` tags to provide specific detail fields in the comment
69
73
- `@see` reference other sources of information like external document links or related entities in the documentation.
70
74
- `@note` add a note for pre or post conditions, or any other notable restrictions or expectations.
71
75
- `@example` for providing example code or related example documentation.
72
-
- `@usecase` provide a simplified method definition for when the full method definition is too complex or noisy. An example is (in the collections API), providing documentation for methods that omit the implicit canBuildFrom.
76
+
73
77
74
78
### Member grouping tags
75
79
@@ -78,11 +82,11 @@ These tags are well-suited to larger types or packages, with many members. They
78
82
These tags are not enabled by default! You must pass the -groups flag to Scaladoc in order to turn them on. Typically the sbt for this will look something like:
79
83
80
84
```scala
81
-
scalacOptions in (Compile, doc) ++= Seq(
85
+
Compile / doc / scalacOptions ++= Seq(
82
86
"-groups"
83
87
)
84
88
```
85
-
Each section should have a single-word identifier that is used in all of these tags, shown as <group> below. By default, that identifier is shown as the title of that documentation section, but you can use @groupname to provide a longer title.
89
+
Each section should have a single-word identifier that is used in all of these tags, shown as `group` below. By default, that identifier is shown as the title of that documentation section, but you can use @groupname to provide a longer title.
86
90
87
91
Typically, you should put @groupprio (and optionally @groupname and @groupdesc) in the Scaladoc for the package/trait/class/object itself, describing what all the groups are, and their order. Then put @group in the Scaladoc for each member, saying which group it is in.
88
92
@@ -108,25 +112,26 @@ Members that do not have a `@group` tag will be listed as “Ungrouped” in the
108
112
If a comment is not provided for an entity at the current inheritance level, but is supplied for the overridden entity at a higher level in the inheritance hierarchy, the comment from the super-class will be used.
109
113
110
114
Likewise if `@param`, `@tparam`, `@return` and other entity tags are omitted but available from a superclass, those comments will be used.
111
-
Explicit
112
115
113
-
For explicit comment inheritance, use the @inheritdoc tag.
114
-
Markup
116
+
### Explicit
115
117
116
-
It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead.
118
+
For explicit comment inheritance, use the @inheritdoc tag.
117
119
118
120
### Markup
119
121
120
122
Scaladoc provides two syntax parsers: `markdown` (default) or `wikidoc`.
123
+
It is still possible to embed HTML tags in Scaladoc (like with Javadoc), but not necessary most of the time as markup may be used instead.
121
124
122
125
#### Markdown
123
126
124
-
Markdown uses [commonmark flavour](https://spec.commonmark.org/current/) with extension of `wikidoc` links for referencing convenience.
127
+
Markdown uses [commonmark flavour](https://spec.commonmark.org/current/) with two custom extensions:
128
+
- `wikidoc` links for referencing convenience
129
+
- `wikidoc` codeblocks with curly braces syntax
125
130
126
131
127
132
#### Wikidoc
128
133
129
-
Wikidoc is syntax used for scala2 scaladoc. It is supported because of many existing source code, however it is unrecommended to use it in new projects.
134
+
Wikidoc is syntax used for scala2 scaladoc. It is supported because of many existing source code, however it is **not** recommended to use it in new projects.
130
135
Wikisyntax can be toggled on with flag `-comment-syntax wiki` globally, or with `@syntax wiki` directive in docstring.
Copy file name to clipboardExpand all lines: docs/docs/usage/scaladoc/settings.md
+19-12Lines changed: 19 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ title: Scaladoc settings
4
4
5
5
# {{page.title}}
6
6
7
-
You can find brief information included in this chapter while calling scaladoc with `-help` flag. However it can be a little tricky if one uses sbt `doc` task.
7
+
This chapter lists the configuration options that can be used when calling scaladoc. Some of the information shown here can be found by calling scaladoc with the `-help` flag.
8
8
9
9
## Parity with scaladoc for Scala 2
10
10
@@ -13,7 +13,7 @@ If you want to know what is current state of compatibility with scaladoc old fla
13
13
14
14
## Providing settings
15
15
16
-
Scaladoc accepts settings provided as a string, e. g.`scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes` or, if called from sbt,
16
+
Supply scaladoc settings as command-line arguments, e.g.,`scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. If called from sbt,
17
17
update the value of `Compile / doc / scalacOptions`, e. g. `Compile / doc / scalacOptions ++= Seq("-d", "output", "-project", "my-project")`
18
18
19
19
## Overview of all available settings
@@ -31,19 +31,25 @@ The logo of your project that appears in a top left corner. To provide compatibi
31
31
The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer`
32
32
33
33
##### -comment-syntax
34
-
The default syntax of comments. Defaults to markdown however wikisyntax can be used.
34
+
The styling language used for parsing comments.
35
+
Currently we support two syntaxes: `markdown` or `wiki`
36
+
If setting is not present, scaladoc defaults `markdown`
35
37
36
38
##### -revision
37
39
Revision (branch or ref) used to build project project. Useful with sourcelinks to prevent them from pointing always to the newest master that is subject to changes.
38
40
39
41
##### -source-links
40
42
Source links provide a mapping between file in documentation and code repository.
A mapping is of the form '\<regex>::\[scaladoc3|scaladoc|javadoc]::\<path>'. You can supply several mappings, separated by commas, as shown in the example.
76
79
77
-
Links to social sites. '[github|twitter|gitter|discord]::link' syntax is used. 'custom::link::white_icon_name::black_icon_name' is also allowed, in this case icons must be present in 'images/'' directory.
Valid values are of the form: '\[github|twitter|gitter|discord]::link'. Scaladoc also supports 'custom::link::white_icon_name::black_icon_name'. In this case icons must be present in 'images/' directory.
87
+
83
88
##### -skip-by-id
84
89
85
90
Identifiers of packages or top-level classes to skip when generating documentation.
@@ -95,6 +100,8 @@ The file from which the root package documentation should be imported.
95
100
##### -author
96
101
97
102
Include authors.
103
+
Adding authors in docstring with `@author Name Surname` by default won't be included in generated html documentation.
104
+
If you would like to label classes with authors explicitly, run scaladoc with this flag.
0 commit comments