chore: add docs and publish ci (#17)

* chore: add docs

* default for concatsource

* fix doc test

* chore: publish ci

Author: ahabhgk

Diff for: .github/workflows/Publish.yaml

@@ -0,0 +1,21 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly-2022-08-06
+          profile: minimal
+          override: true
+      - name: publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish -vv

Diff for: rustfmt.toml

@@ -1,2 +1,3 @@
 max_width = 80
 tab_spaces = 2
+format_code_in_doc_comments = true

Diff for: src/cached_source.rs

@@ -10,6 +10,38 @@ use crate::{
   MapOptions, Source, SourceMap,
 };
 
+/// It tries to reused cached results from other methods to avoid calculations,
+/// usally used after modify is finished.
+///
+/// - [webpack-sources docs](https://github.com/webpack/webpack-sources/#cachedsource).
+///
+/// ```
+/// use rspack_sources::{
+///   BoxSource, CachedSource, ConcatSource, MapOptions, OriginalSource,
+///   RawSource, Source, SourceMap,
+/// };
+///
+/// let mut concat = ConcatSource::new([
+///   Box::new(RawSource::from("Hello World\n".to_string())) as BoxSource,
+///   Box::new(OriginalSource::new(
+///     "console.log('test');\nconsole.log('test2');\n",
+///     "console.js",
+///   )),
+/// ]);
+/// concat.add(OriginalSource::new("Hello2\n", "hello.md"));
+///
+/// let cached = CachedSource::new(concat);
+///
+/// assert_eq!(
+///   cached.source(),
+///   "Hello World\nconsole.log('test');\nconsole.log('test2');\nHello2\n"
+/// );
+/// // second time will be fast.
+/// assert_eq!(
+///   cached.source(),
+///   "Hello World\nconsole.log('test');\nconsole.log('test2');\nHello2\n"
+/// );
+/// ```
 #[derive(Debug)]
 pub struct CachedSource<T> {
   inner: T,
@@ -19,6 +51,7 @@ pub struct CachedSource<T> {
 }
 
 impl<T> CachedSource<T> {
+  /// Create a [CachedSource] with the original [Source].
   pub fn new(inner: T) -> Self {
     Self {
       inner,
@@ -28,7 +61,8 @@ impl<T> CachedSource<T> {
     }
   }
 
-  pub fn inner(&self) -> &T {
+  /// Get the original [Source].
+  pub fn original(&self) -> &T {
     &self.inner
   }
 }

Diff for: src/concat_source.rs

@@ -11,12 +11,54 @@ use crate::{
   BoxSource, MapOptions, Source, SourceMap,
 };
 
-#[derive(Debug)]
+/// Concatenate multiple [Source]s to a single [Source].
+///
+/// - [webpack-sources docs](https://github.com/webpack/webpack-sources/#concatsource).
+///
+/// ```
+/// use rspack_sources::{
+///   BoxSource, ConcatSource, MapOptions, OriginalSource, RawSource, Source,
+///   SourceMap,
+/// };
+///
+/// let mut source = ConcatSource::new([
+///   Box::new(RawSource::from("Hello World\n".to_string())) as BoxSource,
+///   Box::new(OriginalSource::new(
+///     "console.log('test');\nconsole.log('test2');\n",
+///     "console.js",
+///   )),
+/// ]);
+/// source.add(OriginalSource::new("Hello2\n", "hello.md"));
+///
+/// assert_eq!(source.size(), 62);
+/// assert_eq!(
+///   source.source(),
+///   "Hello World\nconsole.log('test');\nconsole.log('test2');\nHello2\n"
+/// );
+/// assert_eq!(
+///   source.map(&MapOptions::new(false)).unwrap(),
+///   SourceMap::from_json(
+///     r#"{
+///       "version": 3,
+///       "mappings": ";AAAA;AACA;ACDA",
+///       "names": [],
+///       "sources": ["console.js", "hello.md"],
+///       "sourcesContent": [
+///         "console.log('test');\nconsole.log('test2');\n",
+///         "Hello2\n"
+///       ]
+///     }"#,
+///   )
+///   .unwrap()
+/// );
+/// ```
+#[derive(Debug, Default)]
 pub struct ConcatSource {
   children: Vec<BoxSource>,
 }
 
 impl ConcatSource {
+  /// Create a [ConcatSource] with [Source]s.
   pub fn new<S, T>(sources: S) -> Self
   where
     T: Into<BoxSource>,
@@ -27,6 +69,7 @@ impl ConcatSource {
     }
   }
 
+  /// Add a [Source] to concat.
   pub fn add<S: Into<BoxSource>>(&mut self, item: S) {
     self.children.push(item.into());
   }

Diff for: src/error.rs

@@ -1,7 +1,9 @@
 use std::{error, fmt, result};
 
+/// An alias for [std::result::Result<T, rspack_sources::Error>].
 pub type Result<T> = result::Result<T, Error>;
 
+/// Error for this crate.
 #[derive(Debug)]
 pub enum Error {
   /// a VLQ string was malformed and data was left over
@@ -10,12 +12,6 @@ pub enum Error {
   VlqNoValues,
   /// Overflow in Vlq handling
   VlqOverflow,
-  /// a mapping segment had an unsupported size
-  BadSegmentSize(u32),
-  /// a reference to a non existing source was encountered
-  BadSourceReference(u32),
-  /// a reference to a non existing name was encountered
-  BadNameReference(u32),
   /// a JSON parsing related failure
   BadJson(serde_json::Error),
 }
@@ -26,13 +22,6 @@ impl fmt::Display for Error {
       Error::VlqLeftover => write!(f, "leftover cur/shift in vlq decode"),
       Error::VlqNoValues => write!(f, "vlq decode did not produce any values"),
       Error::VlqOverflow => write!(f, "vlq decode caused an overflow"),
-      Error::BadSegmentSize(size) => {
-        write!(f, "got {} segments, expected 4 or 5", size)
-      }
-      Error::BadSourceReference(id) => {
-        write!(f, "bad reference to source #{}", id)
-      }
-      Error::BadNameReference(id) => write!(f, "bad reference to name #{}", id),
       Error::BadJson(err) => write!(f, "bad json: {}", err),
     }
   }

Diff for: src/lib.rs

@@ -1,3 +1,8 @@
+//! Rusty [`webpack-sources`](https://github.com/webpack/webpack-sources) port.
+
+#![forbid(unsafe_code)]
+#![deny(missing_docs)]
+
 mod cached_source;
 mod concat_source;
 mod error;
@@ -16,7 +21,8 @@ pub use original_source::OriginalSource;
 pub use raw_source::RawSource;
 pub use replace_source::ReplaceSource;
 pub use source::{
-  BoxSource, MapOptions, Mapping, OriginalLocation, Source, SourceMap,
+  BoxSource, MapOptions, Mapping, OriginalLocation, Source, SourceExt,
+  SourceMap,
 };
 pub use source_map_source::{
   SourceMapSource, SourceMapSourceOptions, WithoutOriginalOptions,

Diff for: src/original_source.rs

@@ -13,13 +13,35 @@ use crate::{
   MapOptions, Source, SourceMap,
 };
 
+/// Represents source code, it will create source map for the source code,
+/// but the source map is created by splitting the source code at typical
+/// statement borders (`;`, `{`, `}`).
+///
+/// - [webpack-sources docs](https://github.com/webpack/webpack-sources/#originalsource).
+///
+/// ```
+/// use rspack_sources::{OriginalSource, MapOptions, Source};
+///
+/// let input = "if (hello()) { world(); hi(); there(); } done();\nif (hello()) { world(); hi(); there(); } done();";
+/// let source = OriginalSource::new(input, "file.js");
+/// assert_eq!(source.source(), input);
+/// assert_eq!(
+///   source.map(&MapOptions::default()).unwrap().mappings(),
+///   "AAAA,eAAe,SAAS,MAAM,WAAW;AACzC,eAAe,SAAS,MAAM,WAAW",
+/// );
+/// assert_eq!(
+///   source.map(&MapOptions::new(false)).unwrap().mappings(),
+///   "AAAA;AACA",
+/// );
+/// ```
 #[derive(Debug, Clone)]
 pub struct OriginalSource {
   value: String,
   name: String,
 }
 
 impl OriginalSource {
+  /// Create a [OriginalSource].
   pub fn new(value: impl Into<String>, name: impl Into<String>) -> Self {
     Self {
       value: value.into(),

Diff for: src/raw_source.rs

@@ -11,13 +11,29 @@ use crate::{
   MapOptions, Source, SourceMap,
 };
 
+/// Represents source code without source map, it will not create source map for the source code.
+///
+/// - [webpack-sources docs](https://github.com/webpack/webpack-sources/#rawsource).
+///
+/// ```
+/// use rspack_sources::{MapOptions, RawSource, Source};
+///
+/// let code = "some source code";
+/// let s = RawSource::from(code.to_string());
+/// assert_eq!(s.source(), code);
+/// assert_eq!(s.map(&MapOptions::default()), None);
+/// assert_eq!(s.size(), 16);
+/// ```
 #[derive(Debug, Clone)]
 pub enum RawSource {
+  /// Represent buffer.
   Buffer(Vec<u8>),
+  /// Represent string.
   Source(String),
 }
 
 impl RawSource {
+  /// Whether the [RawSource] represent a buffer.
   pub fn is_buffer(&self) -> bool {
     matches!(self, Self::Buffer(_))
   }

Diff for: src/replace_source.rs

@@ -12,6 +12,25 @@ use crate::{
   MapOptions, Mapping, OriginalLocation, Source, SourceMap,
 };
 
+/// Decorates a Source with replacements and insertions of source code,
+/// usally used in dependencies
+///
+/// - [webpack-sources docs](https://github.com/webpack/webpack-sources/#replacesource).
+///
+/// ```
+/// use rspack_sources::{OriginalSource, ReplaceSource, Source};
+///
+/// let code = "hello world\n";
+/// let mut source = ReplaceSource::new(OriginalSource::new(code, "file.txt"));
+///
+/// source.insert(0, "start1\n", None);
+/// source.replace(0, 0, "start2\n", None);
+/// source.replace(999, 10000, "end2", None);
+/// source.insert(888, "end1\n", None);
+/// source.replace(0, 999, "replaced!\n", Some("whole"));
+///
+/// assert_eq!(source.source(), "start1\nstart2\nreplaced!\nend1\nend2");
+/// ```
 #[derive(Debug)]
 pub struct ReplaceSource<T> {
   inner: T,
@@ -27,17 +46,20 @@ struct Replacement {
 }
 
 impl<T> ReplaceSource<T> {
+  /// Create a [ReplaceSource].
   pub fn new(source: T) -> Self {
     Self {
       inner: source,
       replacements: Mutex::new(Vec::new()),
     }
   }
 
+  /// Get the original [Source].
   pub fn original(&self) -> &T {
     &self.inner
   }
 
+  /// Insert a content at start.
   pub fn insert(&mut self, start: u32, content: &str, name: Option<&str>) {
     self.replacements.lock().push(Replacement {
       start,
@@ -47,6 +69,7 @@ impl<T> ReplaceSource<T> {
     });
   }
 
+  /// Create a replacement with content at `[start, end)`.
   pub fn replace(
     &mut self,
     start: u32,