Merge pull request #1836 from hannobraun/docs

Update crate-level documentation

README.md

@@ -19,6 +19,7 @@ Fornjot is supported by [**@webtrax-oz**](https://github.com/webtrax-oz), [**@re
 ## Table of Contents
 
 - [**Status**](#status)
+- [**Overview**](#overview)
 - [**Usage**](#usage)
 - [**Community**](#community)
 - [**Get Involved**](#get-involved)
@@ -30,6 +31,23 @@ Fornjot is supported by [**@webtrax-oz**](https://github.com/webtrax-oz), [**@re
 Fornjot is usable for some toy examples, but currently lacks the features for something more advanced. Work to change that is underway.
 
 
+## Overview
+
+This is a list of the crates that make up Fornjot, along with a short description for each, starting with the most basic ones and leading up to the high-level ones:
+
+- [`fj-math`]: Math primitives used by the rest of the Fornjot ecosystem.
+- [`fj-interop`]: Basic types that allow other crates to interoperate, without depending on each other.
+- [`fj-kernel`]: CAD kernel of Fornjot. Defines geometric and topological primitives, and algorithms that operate on those primitives.
+- [`fj-export`]: Exports Fornjot models to external data formats.
+- [`fj-viewer`]: Displays Fornjot models.
+
+[`fj-export`]: https://crates.io/crates/fj-export
+[`fj-interop`]: https://crates.io/crates/fj-interop
+[`fj-kernel`]: https://crates.io/crates/fj-kernel
+[`fj-math`]: https://crates.io/crates/fj-math
+[`fj-viewer`]: https://crates.io/crates/fj-viewer
+
+
 ## Usage
 
 This repository is currently [in flux](https://www.fornjot.app/blog/a-new-direction/) and the documentation previously available here no longer applies. This section will be updated in due time.

crates/fj-export/src/lib.rs

@@ -1,14 +1,10 @@
 //! # Fornjot Exporter
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
-//! code-first CAD application; and collection of libraries that make up the CAD
-//! application, but can be used independently.
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
+//! split into multiple libraries that can be used semi-independently, and this
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
-//! users that just want to create CAD models.
-//!
-//! The purpose of this library is to export Fornjot models to external file
-//! formats.
+//! This library exports Fornjot models to external file formats.
 //!
 //! [Fornjot]: https://www.fornjot.app/
 

crates/fj-interop/src/lib.rs

@@ -1,14 +1,11 @@
 //! # Fornjot Interop Types
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
-//! code-first CAD application; and collection of libraries that make up the CAD
-//! application, but can be used independently.
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
+//! split into multiple libraries that can be used semi-independently, and this
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
-//! users that just want to create CAD models.
-//!
-//! The purpose of this library is to define types that allow other components
-//! of the Fornjot ecosystem to interoperate, without depending on each other.
+//! This library defines types that allow other components of Fornjot to
+//! interoperate, without having to depend on each other.
 //!
 //! [Fornjot]: https://www.fornjot.app/
 

crates/fj-kernel/src/lib.rs

@@ -1,15 +1,11 @@
 //! # Fornjot CAD Kernel
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
-//! code-first CAD application; and collection of libraries that make up the CAD
-//! application, but can be used independently.
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
+//! split into multiple libraries that can be used semi-independently, and this
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
-//! users that just want to create CAD models.
-//!
-//! The CAD kernel is the core of Fornjot: the geometry, the topology, and the
-//! algorithms that handle them. It is separate from the CAD application, and
-//! could be used in other applications.
+//! This library defines geometric and topological primitives, and the
+//! algorithms that operate on them.
 //!
 //!
 //! ## Design Principle

crates/fj-math/src/lib.rs

@@ -1,16 +1,14 @@
 //! # Fornjot Math Library
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
-//! code-first CAD application; and collection of libraries that make up the CAD
-//! application, but can be used independently.
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
+//! split into multiple libraries that can be used semi-independently, and this
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
-//! users that just want to create CAD models.
-//!
-//! This crates provides basic math types for the Fornjot ecosystem. It is built
-//! on [nalgebra] and [Parry], but provides an interface that is specifically
+//! This library provides basic math types for Fornjot. It is built on
+//! [nalgebra] and [Parry], but provides an interface that is specifically
 //! tailored to the needs of Fornjot.
 //!
+//!
 //! ## Failing [`From`]/[`Into`] implementations
 //!
 //! Please note that any [`From`]/[`Into`] implementation that convert floating

crates/fj-viewer/src/lib.rs

@@ -1,14 +1,10 @@
 //! # Fornjot Model Viewer
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
-//! code-first CAD application; and collection of libraries that make up the CAD
-//! application, but can be used independently.
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
+//! split into multiple libraries that can be used semi-independently, and this
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
-//! users that just want to create CAD models.
-//!
-//! This library provides a model viewer which allows basic navigation and
-//! rendering of generated models.
+//! This library provides a viewer for Fornjot models.
 //!
 //! [Fornjot]: https://www.fornjot.app/