From fe42843c7ec6f1e8b04d24fa5fd4006b63e4cb38 Mon Sep 17 00:00:00 2001 From: Daniel Maslowski Date: Mon, 24 Nov 2025 11:46:40 +0100 Subject: [PATCH] docs/extend: extend guiding principles Add a note on usage of `Error` vs `Result`. Rephrase some parts for clarity. Signed-off-by: Daniel Maslowski --- docs/extend.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/extend.md b/docs/extend.md index 203c10c..23d9d74 100644 --- a/docs/extend.md +++ b/docs/extend.md @@ -1,7 +1,7 @@ # Extend with new variants and features -The following is a brief list of guiding principles to extend `intel_fw`. -As a library, it should to adhere to those as requirements in order to provide +These guiding principles are meant to help extending `intel_fw` over time. +As a library, it should adhere to those as requirements in order to provide guarantees to applications working with it. Generally, it should follow the [Rust API guidelines](https://rust-lang.github.io/api-guidelines/about.html). @@ -9,9 +9,18 @@ guarantees to applications working with it. Generally, it should follow the Parsing firmware means looking for and acting on offsets and sizes frequently, and they always need to be checked to stay within the bounds of the given data. -Never `unwrap()`, which means an _intentional panic_, in case something cannot -be found, read, or recognized. Instead, return instances of `Self` for structs, -wrapped in a `Result` or possibly `Option`. +Never `.unwrap()` or `.expect()`, which mean an _intentional panic_, in case +something cannot be found, read, or recognized. Instead, return instances of +`Self` for structs, wrapped in a `Result` or possibly +`Option`. Do not `assert!()` or explicitly `panic!()` either. + +## `Option` or `Result` + +In general, use `Option` for things that might not be found. For example, +a full image from a production system would have an IFD at the beginning, +whereas an ME-only image would not. On the other hand, either image is expected +to contain an FPT, so in this case, provide a `Result`, +because not finding an FPT means that something is clearly wrong with the image. ## Continuous parsing @@ -23,8 +32,9 @@ when there is still remaining data that could be parsed, keep going. ## Let apps provide feedback -In other words, **let the consuming application take care** of taking the result -apart. Nested structures mean that whenever a node in a graph turns into an +Finally, **let the consuming application take care** of taking the result apart. +Nested structures can be thought of as trees, similar to ASTs in programming +languages. Whenever a node in the tree that is a parsing result turns into an `Error` or `None`, other nodes beside it may still provide useful information. That information helps the user of an app to understand the context and possibly report what they are facing or look into the issue themselves.