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
This project uses [Compodoc](https://compodoc.app/) to generate and enforce documentation for all Angular code. Documentation is mandatory and must meet a **100% coverage threshold** to ensure consistent API clarity across the codebase.
4
+
5
+
---
6
+
7
+
## How to Generate Documentation
8
+
9
+
To generate and view the documentation locally:
10
+
11
+
```bash
12
+
npm run docs
13
+
```
14
+
15
+
This will:
16
+
17
+
1. Build the Compodoc documentation.
18
+
2. Launch a local web server to view it (typically on [http://localhost:8080](http://localhost:8080)).
19
+
20
+
---
21
+
22
+
## Documentation Coverage Requirements
23
+
24
+
-**100% Compodoc coverage is required** across all services, components, models, and utilities.
25
+
- All public methods, properties, and classes must be documented using proper JSDoc style comments.
26
+
- Coverage checks are enforced **before every commit** and **during CI/CD** via GitHub Actions.
27
+
28
+
---
29
+
30
+
## Pre-commit Enforcement via Husky
31
+
32
+
Husky is configured to run a **pre-commit hook** that will:
33
+
34
+
- Run Compodoc.
35
+
- Check coverage.
36
+
- Block the commit if documentation coverage is below 100%.
37
+
38
+
If the hook fails, you’ll see output indicating which files or symbols are undocumented.
39
+
40
+
---
41
+
42
+
## CI/CD Enforcement
43
+
44
+
During pull requests and merges, GitHub Actions re-validates documentation coverage.
45
+
46
+
Any PR that does not meet the 100% documentation requirement will be blocked from merging until resolved.
47
+
48
+
---
49
+
50
+
## Tips for Passing Coverage
51
+
52
+
- Use `@Input`, `@Output`, and `@Injectable` annotations with proper descriptions.
53
+
- Document every exported interface, function, method, and variable.
54
+
- Use the `@example` tag for complex methods when helpful.
55
+
- Apply JSDoc on constructor-injected properties using `@param`.
56
+
57
+
---
58
+
59
+
## Output Directory
60
+
61
+
By default, generated documentation lives in:
62
+
63
+
```
64
+
/documentation/
65
+
```
66
+
67
+
This folder is **not committed to the repo** and is only used locally or in build pipelines.
68
+
69
+
---
70
+
71
+
## Need Help?
72
+
73
+
Run the following to see detailed CLI options:
74
+
75
+
```bash
76
+
npx compodoc --help
77
+
```
78
+
79
+
Or visit: [https://compodoc.app](https://compodoc.app)
The OSF Angular project uses [NGXS](https://www.ngxs.io/) as the state management library for Angular applications. NGXS provides a simple, powerful, and TypeScript-friendly framework for managing state across components and services.
4
+
5
+
---
6
+
7
+
## Purpose
8
+
9
+
The goal of using NGXS is to centralize and streamline the handling of application state, reduce boilerplate, and maintain a predictable flow of data and events throughout the OSF Angular app.
10
+
11
+
---
12
+
13
+
## Core Concepts
14
+
15
+
-**State**: Defines a slice of the application state and how it is modified in response to actions.
16
+
-**Actions**: Dispatched to signal state changes or trigger effects (e.g., API calls).
17
+
-**Selectors**: Functions that extract and transform data from the store.
18
+
-**Store**: Centralized container that holds the application state.
19
+
-**Effects** (via `@ngxs-labs/effects` or `@ngxs/store`): Side-effect handling such as HTTP requests, logging, etc.
0 commit comments