docs/extend: extend guiding principles

Add a note on usage of `Error` vs `Result`.
Rephrase some parts for clarity.

Signed-off-by: Daniel Maslowski <[email protected]>

Author: orangecms

docs/extend.md

@@ -1,17 +1,26 @@
 # 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).
 
 ## Do not panic!
 
 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<Self, CustomError>` or possibly `Option<Self>`.
+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<Self, CustomError>` or possibly
+`Option<Self>`. Do not `assert!()` or explicitly `panic!()` either.
+
+## `Option` or `Result`
+
+In general, use `Option<Self>` 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<Self, CustomError>`,
+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.