docs: add documentation

Author: felixfbecker

README.md

@@ -7,21 +7,50 @@
 
 > Adds code intelligence to code views on the web
 
-## API
+## What it does
 
-Use in React TODO
+- Listens to hover and click events on the code view
+- On mouse hovers, determines the line+column position, does an LSP hover request and renders it in a nice tooltip overlay at the token
+- Shows buttons for go-to-definition, find-references, find-implementations
+- When clicking a token, pins the tooltip to that token
+- Highlights the hovered token
 
-Use with native DOM TODO
+## Usage
+
+- Call `createHoverifier()` to create a `Hoverifier` object (there should only be one on the page, to have only one HoverOverlay shown).
+- The Hoverifier exposes an Observable `hoverStateUpdates` that a consumer can subscribe to, which emits all data needed to render the `HoverOverlay` React component.
+- For each code view on the page, call `hoverifier.hoverify()`, passing the position events coming from `findPositionsFromEvents()`.
+- `hoverify()` returns a `Subscription` that will "unhoverify" the code view again if unsubscribed from
 
 ## Development
 
-```shell
-npm i
+```sh
+npm install
 npm test
+
+# Helpful options:
+npm test -- --single-run      # Don't rerun on changes
+npm test -- --browsers Chrome # Only run in Chrome
 ```
 
 Development is done by running tests. [Karma](https://github.com/karma-runner/karma) is used to run
 [Mocha](https://github.com/mochajs/mocha) tests in the browser. You can debug by opening http://localhost:9876/debug.html in
-a browser while the test running is active.
+a browser while the test running is active. The tests will rerun automatically when files are changed.
+
+You can run specific tests by [adding `.only` to `describe` or `it` calls](https://mochajs.org/#exclusive-tests).
+
+## Releases
+
+Releases are done automatically in CI when commits are merged into master by analyzing [Conventional Commit Messages](https://conventionalcommits.org/).
+After running `npm install`, commit messages will be linted automatically when committing.
+You may have to rebase a branch before merging to ensure it has a proper commit history.
+
+## Glossary
 
-All tests are ran against DOM that is generated to match the DOM used by the supported code hosts.
+| Term                | Definition                                                                                                                                                                                  |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Code view           | The DOM element that contains all the line elements                                                                                                                                         |
+| Line number element | The DOM element that contains the line number label for that line                                                                                                                           |
+| Code element        | The DOM element that contains the code for one line                                                                                                                                         |
+| Diff part           | The part of the diff, either base, head or both (if the line didn't change). Each line belongs to one diff part, and therefor to a different commit ID and potentially different file path. |
+| Hover overlay       | Also called tooltip                                                                                                                                                                         |

src/hoverifier.ts

@@ -212,6 +212,11 @@ export const TOOLTIP_DISPLAY_DELAY = 100
 
 export type HoverFetcher = (position: HoveredToken & HoveredTokenContext) => Observable<HoverMerged | null>
 export type JumpURLFetcher = (position: HoveredToken & HoveredTokenContext) => Observable<string | null>
+
+/**
+ * Function responsible for resolving the position of a hovered token
+ * and its diff part to a full context including repository, commit ID and file path.
+ */
 export type ContextResolver = (hoveredToken: HoveredToken) => HoveredTokenContext
 
 export interface HoveredTokenContext extends RepoSpec, RevSpec, FileSpec, ResolvedRevSpec {}