From 523c2c135d1b258c1296228fc9642fc19a9ed202 Mon Sep 17 00:00:00 2001 From: Duke Okojie Date: Sat, 29 Mar 2025 06:10:14 +0100 Subject: [PATCH 1/2] Well documented README.md A well documented readme. --- README.md | 43 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 21f95c4b..adc30b6b 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@ # annotate-snippets -`annotate-snippets` is a Rust library for annotation of programming code slices. +`annotate-snippets` is a Rust library designed to annotate programming code slices, making debugging and diagnostic rendering more intuitive and visually appealing. [![crates.io](https://img.shields.io/crates/v/annotate-snippets.svg)](https://crates.io/crates/annotate-snippets) -[![documentation](https://img.shields.io/badge/docs-master-blue.svg)][Documentation] +[![documentation](https://img.shields.io/badge/docs-master-blue.svg)](https://docs.rs/annotate-snippets/) ![build status](https://github.com/rust-lang/annotate-snippets-rs/actions/workflows/ci.yml/badge.svg) -The library helps visualize meta information annotating source code slices. +About the Library +----------------- +The annotate-snippets library provides tools to annotate source code slices with rich, meta information. It generates visually organized, styled error or informational messages, helping developers quickly pinpoint issues in their code. + +Key Feature: +------------ It takes a data structure called `Snippet` on the input and produces a `String` which may look like this: @@ -14,12 +19,36 @@ which may look like this: Local Development ----------------- - +To build and test the project locally, use the following commands: + cargo build cargo test -When submitting a PR please use [`cargo fmt`][] (nightly). +Formatting +---------- +Before submitting a pull request (PR), ensure the code follows Rust’s formatting standards by running: + + cargo fmt + +Contributing +------------ +When submitting a PR please use [`cargo fmt`](https://github.com/rust-lang/rustfmt) +**NOTE:-** `cargo fmt` requires the nightly version of Rust. + +Core Concepts: +-------------- +`Annotation`: Adding labels or notes to specific parts of code slices for clarity. + +`Snippet`: A small section of programming code to which annotations and diagnostics are applied. + +`Diagnostic Rendering`: Presenting errors or meta information visually for better debugging. + +`Renderer`: A mechanism that transforms the annotated snippets into styled, readable output. + +`Meta Information`: Data that gives additional context or details about a code snippet, like where an error occurred or what caused it. + +`Feature Parity`: Ensuring two tools (or versions of the same tool) have the same capabilities -[`cargo fmt`]: https://github.com/rust-lang/rustfmt +`Error Severity Levels`: Categories that describe how bad an error is (e.g., Error, Warning, Info) to help prioritize fixes. -[Documentation]: https://docs.rs/annotate-snippets/ +`Programming code slices`: are small, specific portions or snippets of a larger codebase. From 8f4aece0b2127931aa5c6a68f597b68819958846 Mon Sep 17 00:00:00 2001 From: Duke Okojie Date: Sat, 29 Mar 2025 06:37:58 +0100 Subject: [PATCH 2/2] docs(readme): update contributing section