scaladoc/documentation/docs/design.md
Scaladoc is divided into 3 modules, that are:
This module contains the core source code and assets (css, js) used for building Scaladoc.
This module contains Scala source code that is compiled to JavaScript. It is used by scaladoc for:
Project that is used for manual testing as well as for end-to-end tests of Scaladoc.
scaladoc is intended to be use with sbt as well as from command line or from any other buildtool. The main entry point
The base pipeline of processing the files is as follows:
Main processing starts from Scaladoc class. This class is reponsible for checking
input settings and setting up DocContext properly, which is wrapping CompilerContext with
all additional information required by Scaladoc.
Then everything goes to ScalaModuleProvider where Members 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, InheritanceInformationTransformer, SealedMarksGraphTransformer.
The last step is serialization members into HTML pages. Everything that lies under package 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:
Unmentioned packages are:
Contains legacy parser for WikiDoc syntax CodeBlocks {{{ }}}.
Package responsible for generation static pages for blog and documentation.
Package havily used during Members creation. Contains preprocessors and parsers to extract DocString comments and
all semantic data from TASTY files.
Worth mentioning are:
Quotes ASTQuotes ASTUtilities to create signatures for given Member.
Utilities for html, IO and JSONs.
The core model class is called Member 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. 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).
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 or
BaseSignatureTest.
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
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 is appended to js resources of published scaladoc. The main entry point is Main 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
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 chapter.