Add more docs

Author: matklad

CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 :tada:
+
+* the carate is renmaed to `text-size` from `text_unit`
+
+Transition table:
+- `TextUnit::of_char(c)`                ⟹ `TextSize::of(c)`
+- `TextUnit::of_str(s)`                 ⟹ `TextSize::of(s)`
+- `TextUnit::from_usize(size)`          ⟹ `TextSize::try_from(size).unwrap_or_else(|| panic!(_))`
+- `unit.to_usize()`                     ⟹ `usize::from(size)`
+- `TextRange::from_to(from, to)`        ⟹ `TextRange::new(from, to)`
+- `TextRange::offset_len(offset, size)` ⟹ `TextRange::from_len(offset, size)`
+- `range.start()`                       ⟹ `range.start()`
+- `range.end()`                         ⟹ `range.end()`
+- `range.len()`                         ⟹ `range.len()`
+- `range.is_empty()`                    ⟹ `range.is_empty()`
+- `a.is_subrange(b)`                    ⟹ `b.contains_range(a)`
+- `a.intersection(b)`                   ⟹ `a.intersect(b)`
+- `a.extend_to(b)`                      ⟹ `a.cover(b)`
+- `range.contains(offset)`              ⟹ `range.contains(point)`
+- `range.contains_inclusive(offset)`    ⟹ `range.contains_inclusive(point)`

src/lib.rs

@@ -1,5 +1,19 @@
 //! Newtypes for working with text sizes/ranges in a more type-safe manner.
 //!
+//! This library can help with two things:
+//!   * Reducing storage requirenments for offsets and ranges, under the
+//!     assumption that 32 bits is enough.
+//!   * Providing standard vocabulary types for applications where text ranges
+//!     are pervasive.
+//!
+//! However, you should not use this library simply because you work with
+//! strings. In the overhelming majority of cases, using `usize` and
+//! `std::ops::Range<usize>` is better. In particular, if you are publishing a
+//! library, using only std types in the interface would make it more
+//! interoperable. Similarly, if you are writing something like a lexer, which
+//! produces, but does not *store* text ranges, than sticking to `usize` would
+//! be better.
+//!
 //! Minimal Supported Rust Version: latest stable.
 
 #![forbid(unsafe_code)]

src/range.rs

@@ -9,20 +9,6 @@ use {
 /// A range in text, represented as a pair of [`TextSize`][struct@TextSize].
 ///
 /// It is a logic error for `start` to be greater than `end`.
-///
-/// # Translation from `text_unit`
-///
-/// - `TextRange::from_to(from, to)`        ⟹ `TextRange::new(from, to)`
-/// - `TextRange::offset_len(offset, size)` ⟹ `TextRange::from_len(offset, size)`
-/// - `range.start()`                       ⟹ `range.start()`
-/// - `range.end()`                         ⟹ `range.end()`
-/// - `range.len()`                         ⟹ `range.len()`
-/// - `range.is_empty()`                    ⟹ `range.is_empty()`
-/// - `a.is_subrange(b)`                    ⟹ `b.contains_range(a)`
-/// - `a.intersection(b)`                   ⟹ `a.intersect(b)`
-/// - `a.extend_to(b)`                      ⟹ `a.cover(b)`
-/// - `range.contains(offset)`              ⟹ `range.contains(point)`
-/// - `range.contains_inclusive(offset)`    ⟹ `range.contains_inclusive(point)`
 #[derive(Default, Copy, Clone, Eq, PartialEq, Hash)]
 pub struct TextRange {
     // Invariant: start <= end

src/size.rs

@@ -21,13 +21,6 @@ use {
 ///
 /// These escape hatches are primarily required for unit testing and when
 /// converting from UTF-8 size to another coordinate space, such as UTF-16.
-///
-/// # Translation from `text_unit`
-///
-/// - `TextUnit::of_char(c)`        ⟹ `TextSize::of(c)`
-/// - `TextUnit::of_str(s)`         ⟹ `TextSize::of(s)`
-/// - `TextUnit::from_usize(size)`  ⟹ `TextSize::try_from(size).unwrap_or_else(|| panic!(_))`
-/// - `unit.to_usize()`             ⟹ `usize::from(size)`
 #[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct TextSize {
     pub(crate) raw: u32,