diff --git a/NOTICE.md b/NOTICE.md index b116155369a8..64b5f9122db7 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -82,9 +82,9 @@ major authors were omitted by oversight. modifications. They were originally authored by Lex Spoon, Som Snytt, Adriaan Moors, Paul Phillips and others. - * dotty.tools.dottydoc: The Dottydoc documentation utility ships some + * dotty.tools.scaladoc: The Scaladoc documentation utility ships some third-party JavaScript and CSS libraries which are located under - dotty-doc/resources/css/, dotty-doc/resources/js/, docs/css/ and + scaladoc/resources/dotty_res/styles/, scaladoc/resources/dotty_res/scripts/, docs/css/ and docs/js/. Please refer to the license header of the concerned files for details. diff --git a/compiler/src/dotty/tools/dotc/config/Printers.scala b/compiler/src/dotty/tools/dotc/config/Printers.scala index 27391154591f..8e13e50e59b7 100644 --- a/compiler/src/dotty/tools/dotc/config/Printers.scala +++ b/compiler/src/dotty/tools/dotc/config/Printers.scala @@ -20,7 +20,7 @@ object Printers { val debug = noPrinter val derive = noPrinter val desugar = noPrinter - val dottydoc = noPrinter + val scaladoc = noPrinter val exhaustivity = noPrinter val gadts = noPrinter val gadtsConstr = noPrinter diff --git a/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala b/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala index 13737f5a1cc7..802e4ff622ac 100644 --- a/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala +++ b/compiler/src/dotty/tools/dotc/config/ScalaSettings.scala @@ -213,9 +213,6 @@ trait AllScalaSettings extends CommonScalaSettings { self: Settings.SettingGroup val YforceInlineWhileTyping: Setting[Boolean] = BooleanSetting("-Yforce-inline-while-typing", "Make non-transparent inline methods inline when typing. Emulates the old inlining behavior of 3.0.0-M3.") - /** Dottydoc specific settings that are not used in scaladoc */ - val docSnapshot: Setting[Boolean] = BooleanSetting("-doc-snapshot", "Generate a documentation snapshot for the current Dotty version") - val projectUrl: Setting[String] = StringSetting ( "-project-url", "project repository homepage", diff --git a/compiler/src/dotty/tools/dotc/core/Comments.scala b/compiler/src/dotty/tools/dotc/core/Comments.scala index 33585411fa6e..183b581ce2e7 100644 --- a/compiler/src/dotty/tools/dotc/core/Comments.scala +++ b/compiler/src/dotty/tools/dotc/core/Comments.scala @@ -143,7 +143,7 @@ object Comments { * @author Felix Mulder */ class CommentExpander { - import dotc.config.Printers.dottydoc + import dotc.config.Printers.scaladoc import scala.collection.mutable def expand(sym: Symbol, site: Symbol)(using Context): String = { @@ -203,7 +203,7 @@ object Comments { case None => // SI-8210 - The warning would be false negative when this symbol is a setter if (ownComment.indexOf("@inheritdoc") != -1 && ! sym.isSetter) - dottydoc.println(s"${sym.span}: the comment for ${sym} contains @inheritdoc, but no parent comment is available to inherit from.") + scaladoc.println(s"${sym.span}: the comment for ${sym} contains @inheritdoc, but no parent comment is available to inherit from.") ownComment.replace("@inheritdoc", "") case Some(sc) => if (ownComment == "") sc @@ -317,7 +317,7 @@ object Comments { val sectionTextBounds = extractSectionText(parent, section) cleanupSectionText(parent.substring(sectionTextBounds._1, sectionTextBounds._2)) case None => - dottydoc.println(s"""${sym.span}: the """" + getSectionHeader + "\" annotation of the " + sym + + scaladoc.println(s"""${sym.span}: the """" + getSectionHeader + "\" annotation of the " + sym + " comment contains @inheritdoc, but the corresponding section in the parent is not defined.") "" } @@ -384,7 +384,7 @@ object Comments { lookupVariable(vname, site) match { case Some(replacement) => replaceWith(replacement) case None => - dottydoc.println(s"Variable $vname undefined in comment for $sym in $site") + scaladoc.println(s"Variable $vname undefined in comment for $sym in $site") } } } diff --git a/compiler/src/dotty/tools/dotc/util/CommentParsing.scala b/compiler/src/dotty/tools/dotc/util/CommentParsing.scala index d8184c0ce5aa..c25660a6225a 100644 --- a/compiler/src/dotty/tools/dotc/util/CommentParsing.scala +++ b/compiler/src/dotty/tools/dotc/util/CommentParsing.scala @@ -8,11 +8,11 @@ package dotty.tools.dotc.util import scala.collection.mutable /** The comment parsing in `dotc` is used by both the comment cooking and the - * dottydoc tool. + * scaladoc tool. * * The comment cooking is used to expand comments with `@inheritdoc` and * `@define` annotations. The rest of the comment is untouched and later - * handled by dottydoc. + * handled by scaladoc. */ object CommentParsing { import Chars._ diff --git a/docs/docs/usage/scaladoc/blog.md b/docs/docs/usage/scaladoc/blog.md index 14d6ff9e1de9..a12804ad4757 100644 --- a/docs/docs/usage/scaladoc/blog.md +++ b/docs/docs/usage/scaladoc/blog.md @@ -7,3 +7,33 @@ title: Built-in blog Scaladoc allows you to include a simple blog in your documentation. For now, it provides only basic features. In the future, we plan to include more advanced features like tagging or author pages. + +Blog is treated a little differently than regular static sites. This article will help you set up your own blog. + +## Proper directory setup + +All your blogposts must be put under `blog/_posts` directory. + + +``` +├── blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +``` + +If you are using yaml [sidebar](./staticSite.html#sidebar) don't forget to place + +``` +sidebar: + - title: Blog +``` + +somewhere inside the `yaml` tree representing the sidebar sections. Scaladoc will attach under that section all of your blogposts. + +## Naming convention + +All the blogpost filenames should start with date in numeric format matching `YYYY-MM-DD`. +Example name is `2015-10-23-dotty-compiler-bootstraps.md`. + + diff --git a/docs/docs/usage/scaladoc/docComments.md b/docs/docs/usage/scaladoc/linkingDocumentation.md similarity index 99% rename from docs/docs/usage/scaladoc/docComments.md rename to docs/docs/usage/scaladoc/linkingDocumentation.md index 87ca35cba26d..f965e8bd8963 100644 --- a/docs/docs/usage/scaladoc/docComments.md +++ b/docs/docs/usage/scaladoc/linkingDocumentation.md @@ -1,5 +1,5 @@ --- -title: API Documentation +title: Linking documentation --- # {{ page.title }} diff --git a/docs/docs/usage/scaladoc/scaladocDocstrings.md b/docs/docs/usage/scaladoc/scaladocDocstrings.md new file mode 100644 index 000000000000..115ef3395c80 --- /dev/null +++ b/docs/docs/usage/scaladoc/scaladocDocstrings.md @@ -0,0 +1,195 @@ +--- +title: Scaladoc docstrings - specific Tags and Features +--- + +# {{page.title}} + +This chapter describes how to correctly write docstrings and how to use all the available features of scaladoc. +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) + + +Scaladoc extends Markdown with additional features, such as linking +to API definitions. This can be used from within static documentation and blog +posts to provide blend-in content. + + +## Where to put docstrings + +Scaladoc comments go before the items they pertain to in a special comment block that starts with a /** and ends with a */, like this: + +```scala +/** Start the comment here + * and use the left star followed by a + * white space on every line. + * + * Even on empty paragraph-break lines. + * + * Note that the * on each line is aligned + * with the second * in /** so that the + * left margin is on the same column on the + * first line and on subsequent ones. + * + * Close the comment with *\/ + * + * If you use Scaladoc tags (@param, @group, etc.), + * remember to put them at separate lines with nothing preceding. + * + * For example: + * + * Calculate the square of the given number + * + * @param d the Double to square + * @return the result of squaring d + */ + def square(d: Double): Double = d * d +``` + +In the example above, this Scaladoc comment is associated with the method square since it is right before it in the source code. + +Scaladoc comments can go before fields, methods, classes, traits, objects. +For now, scaladoc doesn't support straightforward solution to document packages. There is a dedicated github +[issue](https://github.com/lampepfl/dotty/issues/11284), where you can check the current status of the problem. + +For class primary constructors which in Scala coincide with the definition of the class itself, a @constructor tag is used to target a comment to be put on the primary constructor documentation rather than the class overview. + +## Tags + +Scaladoc uses `@` tags to provide specific detail fields in the comments. These include: + +### Class specific tags + +- `@constructor` placed in the class comment will describe the primary constructor. + +### Method specific tags + +- `@return` detail the return value from a method (one per method). + +### Method, Constructor and/or Class tags + +- `@throws` what exceptions (if any) the method or constructor may throw. +- `@param` detail a value parameter for a method or constructor, provide one per parameter to the method/constructor. +- `@tparam` detail a type parameter for a method, constructor or class. Provide one per type parameter. + +### Usage tags + +- `@see` reference other sources of information like external document links or related entities in the documentation. +- `@note` add a note for pre or post conditions, or any other notable restrictions or expectations. +- `@example` for providing example code or related example documentation. + + +### 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: + +```scala +Compile / doc / scalacOptions ++= Seq( + "-groups" +) +``` +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. + +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. +- `@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 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. + +### Other tags + +- `@author` provide author information for the following entity +- `@version` the version of the system or API that this entity is a part of. +- `@since` like `@version` but defines the system or API that this entity was first defined in. +- `@deprecated` marks the entity as deprecated, providing both the replacement implementation that should be used and the version/date at which this entity was deprecated. +- `@syntax ` let you change the parser for docstring. The default syntax is markdown, however you can change it using this directive. Currently available syntaxes are `markdown` or `wiki`, e. g. `@syntax wiki` + +### Macros + +- `@define ` allows use of $name in other Scaladoc comments within the same source file which will be expanded to the contents of ``. + +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. + +Likewise if `@param`, `@tparam`, `@return` and other entity tags are omitted but available from a superclass, those comments will be used. + +### Explicit + +For explicit comment inheritance, use the @inheritdoc tag. + +### Markup + +Scaladoc provides two syntax parsers: `markdown` (default) or `wikidoc`. +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. + +#### Markdown + +Markdown uses [commonmark flavour](https://spec.commonmark.org/current/) with two custom extensions: +- `wikidoc` links for referencing convenience +- `wikidoc` codeblocks with curly braces syntax + + +#### Wikidoc + +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. +Wikisyntax can be toggled on with flag `-comment-syntax wiki` globally, or with `@syntax wiki` directive in docstring. + +Some of the standard markup available: + +``` +`monospace` +''italic text'' +'''bold text''' +__underline__ +^superscript^ +,,subscript,, +[[entity link]], e.g. [[scala.collection.Seq]] +[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]] +``` + +For more info about wiki links look at this [chapter](#linking-to-api) + +Other formatting notes + +- Paragraphs are started with one (or more) blank lines. `*` in the margin for the comment is valid (and should be included) but the line should be blank otherwise. +- Headings are defined with surrounding `=` characters, with more `=` denoting subheadings. E.g. `=Heading=`, `==Sub-Heading==`, etc. +- List blocks are a sequence of list items with the same style and level, with no interruptions from other block styles. Unordered lists can be bulleted using `-`, numbered lists can be denoted using `1.`, `i.`, `I.`, or `a.` for the various numbering styles. In both cases, you must have extra space in front, and more space makes a sub-level. + +The markup for list blocks looks like: + +``` +/** Here is an unordered list: + * + * - First item + * - Second item + * - Sub-item to the second + * - Another sub-item + * - Third item + * + * Here is an ordered list: + * + * 1. First numbered item + * 1. Second numbered item + * i. Sub-item to the second + * i. Another sub-item + * 1. Third item + */ +``` + +### General Notes for Writing Scaladoc Comments + +Concise is nice! Get to the point quickly, people have limited time to spend on your documentation, use it wisely. +Omit unnecessary words. Prefer returns X rather than this method returns X, and does X,Y & Z rather than this method does X, Y and Z. +DRY - don’t repeat yourself. Resist duplicating the method description in the @return tag and other forms of repetitive commenting. + +More details on writing Scaladoc + +Further information on the formatting and style recommendations can be found in Scala-lang scaladoc style guide. + +## Linking to API + +Scaladoc allows linking to API documentation with Wiki-style links. Linking to +`scala.collection.immutable.List` is as simple as +`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./linkingDocumentation.html#definition-links). diff --git a/docs/docs/usage/scaladoc/settings.md b/docs/docs/usage/scaladoc/settings.md new file mode 100644 index 000000000000..bc5e10c8c1c1 --- /dev/null +++ b/docs/docs/usage/scaladoc/settings.md @@ -0,0 +1,119 @@ +--- +title: Scaladoc settings +--- + +# {{page.title}} + +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. + +## Parity with scaladoc for Scala 2 + +Scaladoc has been rewritten from scratch and some of the features turned out to be useless in the new context. +If you want to know what is current state of compatibility with scaladoc old flags, you can visit this issue for tracking [progress](https://github.com/lampepfl/dotty/issues/11907). + +## Providing settings + +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, +update the value of `Compile / doc / scalacOptions`, e. g. `Compile / doc / scalacOptions ++= Seq("-d", "output", "-project", "my-project")` + +## Overview of all available settings + +##### -project +The name of the project. To provide compatibility with Scala2 aliases with `-doc-title` + +##### -project-version +The current version of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-version` + +##### -project-logo +The logo of your project that appears in a top left corner. To provide compatibility with Scala2 aliases with `-doc-logo` + +##### -project-footer +The string message that appears in a footer section. To provide compatibility with Scala2 aliases with `-doc-footer` + +##### -comment-syntax +The styling language used for parsing comments. +Currently we support two syntaxes: `markdown` or `wiki` +If setting is not present, scaladoc defaults `markdown` + +##### -revision +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. + +##### -source-links +Source links provide a mapping between file in documentation and code repository. + +Example source links is: +`-source-links:docs=github://lampepfl/dotty/master#docs` + +Accepted formats: + +\=\ +\ + +where \ is one of following: + - `github:///[/revision][#subpath]` + will match https://github.com/$organization/$repository/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber] + when revision is not provided then requires revision to be specified as argument for scaladoc + - `gitlab:///` + will match https://gitlab.com/$organization/$repository/-/\[blob|edit]/$revision\[/$subpath]/$filePath\[$lineNumber] + when revision is not provided then requires revision to be specified as argument for scaladoc + - \ + +\ is a format for `doc-source-url` parameter from old scaladoc. +NOTE: We only supports `€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, + €{FILE_PATH}, and €{FILE_LINE} patterns. + + +Template can defined only by subset of sources defined by path prefix represented by ``. +In such case paths used in templates will be relativized against `` + + + +##### -external-mappings + +Mapping between regexes matching classpath entries and external documentation. + +Example external mapping is: +`-external-mappings:.*scala.*::scaladoc3::http://dotty.epfl.ch/api/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/` + +A mapping is of the form '\::\[scaladoc3|scaladoc|javadoc]::\'. You can supply several mappings, separated by commas, as shown in the example. + +##### -social-links + +Links to social sites. For example: + +`-social-links:github::https://github.com/lampepfl/dotty,gitter::https://gitter.im/scala/scala,twitter::https://twitter.com/scala_lang` + +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. + +##### -skip-by-id + +Identifiers of packages or top-level classes to skip when generating documentation. + +##### -skip-by-regex + +Regexes that match fully qualified names of packages or top-level classes to skip when generating documentation. + +##### -doc-root-content + +The file from which the root package documentation should be imported. + +##### -author + +Adding authors in docstring with `@author Name Surname` by default won't be included in generated html documentation. +If you would like to label classes with authors explicitly, run scaladoc with this flag. + +##### -groups + +Group similar functions together (based on the @group annotation) + +##### -private + +Show all types and members. Unless specified, show only public and protected types and members. + +##### -doc-canonical-base-url + +A base URL to use as prefix and add `canonical` URLs to all pages. The canonical URL may be used by search engines to choose the URL that you want people to see in search results. If unset no canonical URLs are generated. + +##### -siteroot + +A directory containing static files from which to generate documentation. Default directory is `./docs` diff --git a/docs/docs/usage/scaladoc/specificTags.md b/docs/docs/usage/scaladoc/specificTags.md deleted file mode 100644 index 0aa794add501..000000000000 --- a/docs/docs/usage/scaladoc/specificTags.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Scaladoc-specific Tags and Features ---- - -# {{page.title}} - -Scaladoc extends Markdown with additional features, such as linking -to API definitions. This can be used from within static documentation and blog -posts to provide blend-in content. - -## Linking to API - -Scaladoc allows linking to API documentation with Wiki-style links. Linking to -`scala.collection.immutable.List` is as simple as -`[[scala.collection.immutable.List]]`. For more information on the exact syntax, see [doc comment documentation](./docComments.html#definition-links). diff --git a/docs/docs/usage/scaladoc/staticSite.md b/docs/docs/usage/scaladoc/staticSite.md index b84e84716214..f94318497729 100644 --- a/docs/docs/usage/scaladoc/staticSite.md +++ b/docs/docs/usage/scaladoc/staticSite.md @@ -92,14 +92,13 @@ Layouts must be placed in a `_layouts` directory in the site root: └── index.html ``` -Sidebar -======= +## Sidebar + Scaladoc by default uses layout of files in `docs` directory to create table of content. There is also ability to override it by providing a `sidebar.yml` file in the site root: ```yaml sidebar: - title: Blog - url: blog/index.html - title: Docs url: docs/index.html - title: Usage @@ -114,12 +113,43 @@ The `sidebar` key is mandatory, as well as `title` for each element. The default table of contents allows you to have subsections - albeit the current depth limit is 2 however it accepts both files and directories and latter can be used to provide deeper structures. -The items which have on the `subsection` level does not accepts `url`. +The items must provide either `subsection` or `url` but not both at once! +The only exception is `Blog` which is only a `title` and behaves differently. +You can read more about blog [here](blog.md). ``` ├── blog -│ └── _posts -│ └── 2016-12-05-implicit-function-types.md +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html ├── index.html └── sidebar.yml ``` + +## Static resources + +You can attach static resources (pdf, images) to your documentation by using two dedicated directories: +`resources` and `images`. When you upload your assests under any of these directories you can reference them in markdown +as if they were relatively at the same level. + +For example, consider the following situation: + +``` +├── blog +│ ├── _posts +│ │ └── 2016-12-05-implicit-function-types.md +│ └── index.html +├── index.html +├── resources +│ └── my_file.pdf +├── images +│ └── my_image.png +└── sidebar.yml + +``` + +You can refer to the assets from within any of the files using markdown links: + +``` +This is my blogpost. Here is the image ![](my_image.png) and here is my [pdf](my_file.pdf) +``` diff --git a/docs/sidebar.yml b/docs/sidebar.yml index 980ecca16edb..e62606aed0e7 100644 --- a/docs/sidebar.yml +++ b/docs/sidebar.yml @@ -1,6 +1,5 @@ sidebar: - title: Blog - url: blog/index.html - title: Usage subsection: - title: Getting Started @@ -17,8 +16,6 @@ sidebar: url: docs/usage/cbt-projects.html - title: Scaladoc url: docs/usage/scaladoc - - title: Dottydoc [Legacy] - url: docs/usage/dottydoc.html - title: Reference subsection: - title: Overview diff --git a/scaladoc/README.md b/scaladoc/README.md index c55a256e342d..9d5ebc11bde3 100644 --- a/scaladoc/README.md +++ b/scaladoc/README.md @@ -31,35 +31,28 @@ python3 -m http.server 8080 ``` And afterwards point your browser to or - for this project and for Dotty documentation + for this project and for Dotty documentation respectively. It's not strictly necessary to go through an HTTP server, but because of CORS the documentation won't work completely if you don't. -## CLI Documentation +## CLI and SBT Documentation -CLI command for running our tool is in form: `sbt main -n -o -t -cp -s { } -d ` where: - -- ``: name of module in generated documentation -- ``: location where documentation should be created -- ``: is list of dirs or jars that contains tasty files that should be documented -- ``: classpath that was used to generate tasty files -- ``: links to source files of module that are used to link symbols on pages to their source file. They need to be supplied in form: - `local_dir=remote_dir#line_suffix` e.g. `src/main/scala=https://github.com/lampepfl/scaladoc/tree/master/src/main/scala#L` -- ``: directory of static documentation that you would like to render with API documentation. +The preferred way to use scaladoc is calling it from sbt `Compile/doc` task or to use CLI interface provided inside `dotty/bin/scaladoc` bash script. +More information about specific scaladoc flags you can find inside [Usage docs](https://dotty.epfl.ch/docs/usage/scaladoc/settings.html) ## Developing At least two of our contributors use [Metals](https://scalameta.org/metals/) to work on the project. -For every PR, we build documentation for scaladoc and Dotty. For example, for -PR 123 you can find them at: +For every PR named with prefix `scaladoc/`, we build documentation for scaladoc and Dotty. For example, for +PR `scaladoc/update-docs` you can find them at: -- -- -- +- +- +- Note that these correspond to the contents of `output` directory - that's precisely what they are. @@ -73,21 +66,18 @@ You can also find the result of building the same sites for latest `master` at: ### Testing Most tests rely on comparing signatures (of classes, methods, objects etc.) extracted from the generated documentation -to signatures found in source files. Such tests are defined using [MultipleFileTest](test/dotty/tools/scala3doc/MultipleFileTest.scala) class -and its subtypes (such as [SingleFileTest](test/dotty/tools/scala3doc/SingleFileTest.scala)) +to signatures found in source files. Such tests are defined using [SignatureTest](test/dotty/tools/scaladoc/signatures/SignatureTest.scala) class +and its subtypes (such as [TranslatableSignaturesTestCases](test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala)) WARNING: As the classes mentioned above are likely to evolve, the description below might easily get out of date. In case of any discrepancies rely on the source files instead. -`MultipleFileTest` requires that you specify the names of the files used to extract signatures, +`SignatureTest` requires that you specify the names of the files used to extract signatures, the names of directories containing corresponding TASTY files and the kinds of signatures from source files (corresponding to keywords used to declare them like `def`, `class`, `object` etc.) whose presence in the generated documentation will be checked (other signatures, when missing, will be ignored). -The mentioned source files should be located directly inside `src/main/scala/tests` directory +The mentioned source files should be located directly inside [](../scaladoc-testcases/src/tests) directory but the file names passed as parameters should contain neither this path prefix nor `.scala` suffix. -The TASTY folders are expected to be located in `target/${dottyVersion}/classes/tests` (after successful compilation of the project) -and similarly only their names relative to this path should be provided as tests' parameters. -For `SingleFileTest` the name of the source file and the TASTY folder are expected to be the same. By default it's expected that all signatures from the source files will be present in the documentation but not vice versa (because the documentation can contain also inherited signatures). @@ -129,20 +119,6 @@ class Bar Otherwise the implementation would be treated as a part of the signature. -## Roadmap - -1. Publish an initial version of the tool together with an SBT plugin -1. Replace Dottydoc as the dedicated tool for documenting Dotty code - - This includes: - - - supporting Dotty's doc pages - - releasing together with Dotty as the dedicated documentation tool - -1. Support all kinds of Dotty definition and generate documentation for the - standard library -1. Reach feature parity with Scaladoc - ## Contributing We're happy that you'd like to help us! diff --git a/scaladoc/documentation/docs/design.md b/scaladoc/documentation/docs/design.md index 3ca5639cf430..475c50bab0ae 100644 --- a/scaladoc/documentation/docs/design.md +++ b/scaladoc/documentation/docs/design.md @@ -1,7 +1,120 @@ # Design of scaladoc -**BEWARE this is not complete documentation yet but rather a draft mainly to test linking from static site to code** +Scaladoc is divided into 3 modules, that are: +- scaladoc +- scaladoc-js +- scaladoc-testcases -## Interface +##### scaladoc -scaladoc is intednted to be use with sbt as well as from commend line or from other buildtools. The main entry point to processing is [Main](dotty.tools.scaladoc.Main$) class with [[dotty.tools.scaladoc.Main$.main]]. \ No newline at end of file +This module contains the core source code and assets (css, js) used for building Scaladoc. + +##### scaladoc-js + +This module contains Scala source code that is compiled to JavaScript. It is used by scaladoc for: +- searchbar +- social links +- snippets processor + +##### scaladoc-testcases + +Project that is used for manual testing as well as for end-to-end tests of Scaladoc. + +## scaladoc + +### Interface + +scaladoc is intended to be use with sbt as well as from command line or from any other buildtool. The main entry point +- for sbt is [dotty.tools.dottydoc.Main](../../src/dotty/tools/dottydoc/Main.scala) + This class is just for compatibility with old dottydoc and should be removed in the near future. +- for CLI is [dotty.tools.scaladoc.Main](../../src/dotty/tools/scaladoc/Main.scala) + +### The base pipeline + +The base pipeline of processing the files is as follows: + +1. Gathering code data from TASTY files. +2. Creation of Members +3. Apply transformers +4. Rendering the members into HTML + +Main processing starts from [Scaladoc](../../src/dotty/tools/scaladoc/Scaladoc.scala) class. This class is reponsible for checking +input settings and setting up [DocContext](../../src/dotty/tools/scaladoc/DocContext.scala) properly, which is wrapping `CompilerContext` with +all additional information required by Scaladoc. + +Then everything goes to [ScalaModuleProvider](../../src/dotty/tools/scaladoc/ScalaModuleProvider.scala) where [Members](../../src/dotty/tools/scaladoc/api.scala) are created and then +transformations are applied. + +Transformers are used to add additional data that could not be added at `Member`'s tree creation time. + +Example transformers used are: [ImplicitMembersExtensionTransformer](../../src/dotty/tools/scaladoc/transformers/ImplicitMembersExtensionTransformer.scala), +[InheritanceInformationTransformer](../../src/dotty/tools/scaladoc/transformers/InheritanceInformationTransformer.scala), +[SealedMarksGraphTransformer](../../src/dotty/tools/scaladoc/transformers/SealedMarksGraphTransformer.scala). + +The last step is serialization members into HTML pages. Everything that lies under package [dotty.tools.scaladoc.renderers](../../src/dotty/tools/scaladoc/renderers). It's worth noticing that whole template of page is coded as HTML building DSL like scalatags. The DocStrings are rendered by: +- if they are Markdown syntax comments - by flexmark dependency +- if they are WikiDoc syntax comments - by our own implementation + +Unmentioned packages are: +#### [dotty.tools.scaladoc.parsers](../../src/dotty/tools/scaladoc/parsers) + +Contains legacy parser for WikiDoc syntax CodeBlocks `{{{ }}}`. + +#### [dotty.tools.scaladoc.site](../../src/dotty/tools/scaladoc/site) + +Package responsible for generation static pages for blog and documentation. + +#### [dotty.tools.scaladoc.tasty](../../src/dotty/tools/scaladoc/tasty) + +Package havily used during `Members` creation. Contains preprocessors and parsers to extract `DocString` comments and +all semantic data from TASTY files. + +Worth mentioning are: +- [TypesSupport](../../src/dotty/tools/scaladoc/tasty/TypesSupport.scala) - used to gather types that are human readable out of `Quotes` AST +- [ClassLikeSupport](../../src/dotty/tools/scaladoc/tasty/ClassLikeSupport.scala) - used to gather Members information out of `Quotes` AST + +#### [dotty.tools.scaladoc.translators](../../src/dotty/tools/scaladoc/translators) + +Utilities to create signatures for given Member. + +#### [dotty.tools.scaladoc.util](../../src/dotty/tools/scaladoc/util) + +Utilities for html, IO and JSONs. + +### Important model classes + +The core model class is called [Member](../../src/dotty/tools/scaladoc/api.scala) which aggregates all semantic data about some element of code. +It can represent Package, Class, Method etc. Members create Tree-like structure just like Classes do. Every `Member` has it's own identifier called +[DRI](../../src/dotty/tools/scaladoc/DRI.scala). `DRI` is easily serializable and unique. It's name is related to `DRI` model class from dokka, +on which scaladoc was firstly based. `DRI` lets you get URL of resource easily, doesn't matter if this is symbol from the same project or any external +dependency (given that correct external dependency is configured). + +### Testing + +In project we have some unit tests and end-to-end tests. +Unit tests are nothing special, just put them under `test` directory. +If you would like to creat some end-to-end tests you should visit [ScaladocTest](../../test/dotty/tools/scaladoc/ScaladocTest.scala) or +[BaseSignatureTest](../../test/dotty/tools/scaladoc/signatures/SignatureTest.scala). +The former is useful for any end-to-end tests, especially when used with JSoup html parsing. +The latter is used to compare expected/actual signatures of classes/methods etc. + +To run tests just run `sbt scaladoc/test` + +### Hack methods + +Across the project there are multiple `hackXXX` methods around. The reasons why method is called like that can be various, however they probably do +some nasty casting, try-catching or any other procedure that was becuase of TASTY/dotty shortcomings or minor bugs. In the near future we should +revisit each of them and fix them on `dotty side or fix in any other way. + +## scaladoc-js + +### Interface + +scaladoc-js is appended to js resources of published scaladoc. The main entry point is [Main](../../../scaladoc-js/src/Main.scala) +As a main method just append your javascripts transfomers that you find sufficient. +For now scaladoc-js handles Social Links and Searchbar, though there are plans to rewrite more js scipts like Diagram handler to Scala.js + +## scaladoc-testcases + +There is no general rule how to treat this package. If you want to use it as `easy to look up scaladoc output` module, just add your scala definitions +somewhere under `src` directory and run `sbt scaladoc/generateTestcasesDocumentation`. If you would like to use it as end-to-end test sourcecode input, check out [Testing](#testing) chapter. diff --git a/scaladoc/resources/dotty_res/images/scaladoc_logo.svg b/scaladoc/resources/dotty_res/images/scaladoc_logo.svg index 40101df90c9d..177451963957 100644 --- a/scaladoc/resources/dotty_res/images/scaladoc_logo.svg +++ b/scaladoc/resources/dotty_res/images/scaladoc_logo.svg @@ -1 +1 @@ - \ No newline at end of file + \ No newline at end of file diff --git a/scaladoc/src/dotty/tools/scaladoc/ScalaModuleCreator.scala b/scaladoc/src/dotty/tools/scaladoc/ScalaModuleProvider.scala similarity index 100% rename from scaladoc/src/dotty/tools/scaladoc/ScalaModuleCreator.scala rename to scaladoc/src/dotty/tools/scaladoc/ScalaModuleProvider.scala diff --git a/scaladoc/src/dotty/tools/scaladoc/renderers/WikiDocRenderer.scala b/scaladoc/src/dotty/tools/scaladoc/renderers/DocRenderer.scala similarity index 100% rename from scaladoc/src/dotty/tools/scaladoc/renderers/WikiDocRenderer.scala rename to scaladoc/src/dotty/tools/scaladoc/renderers/DocRenderer.scala diff --git a/scaladoc/src/dotty/tools/scaladoc/site/SidebarParser.scala b/scaladoc/src/dotty/tools/scaladoc/site/SidebarParser.scala index ff3c2ae2fc9f..2cb8be059aeb 100644 --- a/scaladoc/src/dotty/tools/scaladoc/site/SidebarParser.scala +++ b/scaladoc/src/dotty/tools/scaladoc/site/SidebarParser.scala @@ -24,7 +24,7 @@ object Sidebar: private object RawTypeRef extends TypeReference[RawInnerTpe] private def toSidebar(r: RawInput): Sidebar = r match - case RawInput(title, url, list) if title.nonEmpty && url.nonEmpty && list.isEmpty() => + case RawInput(title, url, list) if title.nonEmpty && url.nonEmpty && list.isEmpty() || title == "Blog" => Sidebar.Page(title, url) case RawInput(title, url, list) if title.nonEmpty && url.isEmpty && !list.isEmpty() => Sidebar.Category(title, list.asScala.map(toSidebar).toList) diff --git a/scaladoc/src/dotty/tools/scaladoc/tasty/comments/Preparser.scala b/scaladoc/src/dotty/tools/scaladoc/tasty/comments/Preparser.scala index f62b9983584a..7e149f7d4a9a 100644 --- a/scaladoc/src/dotty/tools/scaladoc/tasty/comments/Preparser.scala +++ b/scaladoc/src/dotty/tools/scaladoc/tasty/comments/Preparser.scala @@ -138,7 +138,7 @@ object Preparser { bodyTags.keys.toSeq flatMap { case stk: SymbolTagKey if (stk.name == key.name) => Some(stk) case stk: SimpleTagKey if (stk.name == key.name) => - // dottydoc.println(s"$span: tag '@${stk.name}' must be followed by a symbol name") + // scaladoc.println(s"$span: tag '@${stk.name}' must be followed by a symbol name") None case _ => None } @@ -146,7 +146,7 @@ object Preparser { for (key <- keys) yield { val bs = (bodyTags remove key).get // if (bs.length > 1) - // dottydoc.println(s"$span: only one '@${key.name}' tag for symbol ${key.symbol} is allowed") + // scaladoc.println(s"$span: only one '@${key.name}' tag for symbol ${key.symbol} is allowed") (key.symbol, bs.head) } SortedMap.empty[String, String] ++ pairs