chore(docs): add example usage

a11ywatch · Oct 11, 2023 · 29f06f3 · 29f06f3
1 parent 866827c
commit 29f06f3
Show file tree

Hide file tree

Showing 5 changed files with 40 additions and 5 deletions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/accessibility-rs/Cargo.toml b/accessibility-rs/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "accessibility-rs"
-version = "0.0.8"
+version = "0.0.10"
 authors = ["The A11yWatch Project Developers", "Jeff Mendez <[email protected]>"]
 edition = "2021"
 license = "MIT OR Apache-2.0"

diff --git a/accessibility-rs/src/engine/audit/auditor.rs b/accessibility-rs/src/engine/audit/auditor.rs
@@ -7,7 +7,7 @@ use markup5ever::local_name;
 use slotmap::DefaultKey;
 use taffy::Taffy;
 
-/// the intro to an audit
+/// The configuration for auditing
 pub struct Auditor<'a> {
     /// the html document
     pub document: &'a Html,
@@ -23,6 +23,7 @@ pub struct Auditor<'a> {
 }
 
 impl<'a> Auditor<'a> {
+    /// Create a new auditor that can be used to validate accessibility
     pub fn new(
         document: &'a Html,
         css_rules: &str,

diff --git a/accessibility-rs/src/engine/issue.rs b/accessibility-rs/src/engine/issue.rs
@@ -13,7 +13,7 @@ pub struct Clip {
     pub width: u32,
 }
 
-/// issue details
+/// Extra help information for the issue
 #[derive(Default, Debug, Serialize, Deserialize)]
 pub struct RunnerExtras {
     /// the url to get more information on the issue
@@ -24,7 +24,7 @@ pub struct RunnerExtras {
     pub impact: &'static str,
 }
 
-/// issue details
+/// Details of the problem
 #[derive(Default, Debug, Serialize, Deserialize)]
 pub struct Issue {
     /// the context of the issue or raw html

diff --git a/accessibility-rs/src/lib.rs b/accessibility-rs/src/lib.rs
@@ -1,3 +1,37 @@
+#![warn(missing_docs)]
+
+//! Audit html to see how it complies with WCAG
+//! standards.
+//!
+//! Accessibility-RS is a powerful web accessibility
+//! engine that can replicate websites without
+//! a browser to get complex accessibility reports.
+//!
+//! # How to use Accessibility-RS
+//!
+//! There are a couple of ways to use Accessibility-RS:
+//!
+//! - **Audit** perform an audit against an html page.
+//!   - [`audit`] is used to audit a web page for issues.
+//!
+//! [`audit`]: fn.audit.html#method.audit
+//!
+//! # Examples
+//!
+//! A basic WCAG audit for a website:
+//!
+//! ```no_run
+//! use accessibility_rs::{audit, AuditConfig};
+//!
+//! fn main() {
+//!     // pass in the html, and css if the page came from a headless browser
+//!     let config = AuditConfig::basic("<html>...</html>");
+//!     let audit = audit(&config);
+//!     println!("{:?}", audit);
+//! }
+//! ```
+//!
+
 #[macro_use]
 extern crate lazy_static;
 #[macro_use]