From ef9545413d0e41c0116594dbe3bb9f48ed36a9cc Mon Sep 17 00:00:00 2001 From: "Mark \"Justin\" Waks" Date: Wed, 6 Feb 2019 13:01:51 -0500 Subject: [PATCH] In the Scaladoc Overview, flesh out the @group tags The existing Scaladoc for the `@group` tags was scanty, and missing some critical information. Fleshed that out to hopefully be clearer and more usable. --- _overviews/scaladoc/for-library-authors.md | 33 ++++++++++++++++++++-- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/_overviews/scaladoc/for-library-authors.md b/_overviews/scaladoc/for-library-authors.md index b544a9dd48..9d3fc9e9a3 100644 --- a/_overviews/scaladoc/for-library-authors.md +++ b/_overviews/scaladoc/for-library-authors.md @@ -94,12 +94,39 @@ include: ### Member grouping tags + +These tags are well-suited to larger types or packages, with many members. +They allow you to organize the Scaladoc page into distinct sections, with +each one shown separately, in the order that you choose. + +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: +``` +scalacOptions in (Compile, doc) ++= Seq( + "-groups" +) +``` + +Each section should have a single-word identifier that is used in all of +these tags, shown as `` below. By default, that identifier is +shown as the title of that documentation section, but you can use +`@groupname` to provide a longer title. + +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. + +Members that do not have a `@group` tag will be listed as "Ungrouped" in +the resulting documentation. + - `@group ` - mark the entity as a member of the `` group. - `@groupname ` - provide an optional name for the group. `` is displayed as the group header -- before the group description. + before the group description. - `@groupdesc ` - add optional descriptive text to display under the group name. Supports multiline - formatted text. -- `@groupprio` - control the order of the group on the page. Defaults to 0. Ungrouped elements have + formatted text. +- `@groupprio ` - control the order of the group on the page. Defaults to 0. Ungrouped elements have an implicit priority of 1000. Use a value between 0 and 999 to set a relative position to other groups. Low values will appear before high values.