dnrops
/
Tokamak
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add "Modular structure" section to `README.md` (#137) 

* Add "Modular structure" section to `README.md`

This clarifies the general structure of the `Tokamak` package and lays out "the underscore rules" to indicate "package private" access for symbols that aren't intended for public use.

* Refine wording in the "Modular structure" section
This commit is contained in:
Max Desiatov 2020-07-01 14:41:24 +01:00 committed by GitHub
parent 5adc7b2cff
commit f85e26a350
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 35 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@ -113,18 +113,33 @@ This way both [Semantic UI](https://semantic-ui.com/) styles and [moment.js](htt
localized date formatting (or any arbitrary style/script/font added that way) are available in your
app.
## Acknowledgments
- Thanks to the [Swift community](https://swift.org/community/) for
building one of the best programming languages available!
- Thanks to [SwiftWebUI](https://github.com/SwiftWebUI/SwiftWebUI),
[Render](https://github.com/alexdrone/Render),
[ReSwift](https://github.com/ReSwift/ReSwift), [Katana
UI](https://github.com/BendingSpoons/katana-ui-swift) and
[Komponents](https://github.com/freshOS/Komponents) for inspiration!
## Contributing
### Modular structure
Tokamak is built with modularity in mind, providing a cross-platform `TokamakCore` module and
separate modules for platform-specific renderers. Currently, the only available renderer module
is `TokamakDOM`, but we intend to provide other renderers in the future, such as `TokamakHTML`
for static websites and server-side rendering. Tokamak users only need to import a renderer module
they would like to use, while `TokamakCore` is hidden as an "internal" `Tokamak` package target.
Unfortunately, Swift does not allow us to specify that certain symbols in `TokamakCore` are private
to a package, but they need to stay `public` for renderer modules to get access to them. Thus, the
current workaround is to mark those symbols with underscores in their names to indicate this. It
can be formulated as these "rules":
1. If a symbol is restricted to a module and has no `public` access control, no need for an underscore.
2. If a symbol is part of a public renderer module API (e.g. `TokamakDOM`), no need for an underscore,
users may use those symbols directly, and it is re-exported from `TokamakCore` by the renderer module
via `public typealias`.
3. If a function or a type have `public` on them only by necessity to make them available in `TokamakDOM`,
but unavailable to users (or not intended for public use), underscore is needed to indicate that.
The benefit of separate modules is that they allow us to provide separate renderers for different platforms.
Users can pick and choose what they want to use, e.g. purely static websites would use only `TokamakHTML`,
single-page apps would use `TokamakDOM`, maybe in conjuction with `TokamakHTML` for pre-rendering. As we'd
like to try to implement a native renderer for Android at some point, probably in a separate `TokamakAndroid`
module, Android apps would use `TokamakAndroid` with no need to be aware of any of the web modules.
### Sponsorship
If this library saved you any amount of time or money, please consider [sponsoring
@ -171,6 +186,16 @@ unacceptable behavior to conduct@tokamak.dev.
[Carson Katri](https://github.com/carson-katri),
[Jed Fox](https://jedfox.com), [Max Desiatov](https://desiatov.com).
## Acknowledgments
- Thanks to the [Swift community](https://swift.org/community/) for
building one of the best programming languages available!
- Thanks to [SwiftWebUI](https://github.com/SwiftWebUI/SwiftWebUI),
[Render](https://github.com/alexdrone/Render),
[ReSwift](https://github.com/ReSwift/ReSwift), [Katana
UI](https://github.com/BendingSpoons/katana-ui-swift) and
[Komponents](https://github.com/freshOS/Komponents) for inspiration!
## License
Tokamak is available under the Apache 2.0 license. See the