[DRAFT] Updating README and API documentation #1

Capitalize title: The Basic Workflow

I think we can be more certain about what we're saying here: its not possible to make assumptions about its format, so we will need to know the format (properties and possible sub-nodes) we are looking for ahead of time.

to be searched -> that we're looking for.

dtb_stat_node is really just a nice-to-have, its doesnt provide any practical uses for the dtb. While it can be nice to print this info, I'd phrase this step as something like For debugging it can be helpful to view some basic info about the node, like the number of properties/children/siblings. Using the function dtb_stat_node we can get this information.

the end of this sentence has a weird flow, try the dtb_get_propordtb_find_prop functions can be used to locate the property of interest.

code formatting starts too early.
Also all of these dot points are missing full stops on the end

again, this is nice for debugging info and viewing the layout of the tree, but its not needed for general use of the library. In fact using it will slow down your code, so I wouldnt advise it as a good idea. Mentioning that it exists and where it might be useful is good I think, but not for general operation.

Leftover from a previous revision I think :)

Lets keep any high level stuff about the format at the start of the docs, I dont think halfway through a function description is a good place to mention it. And these docs do expect you to be familiar with the device tree format, so I dont there's a need to repeat information that is covered in the DT spec. This may be harsh, but this isn't an educational resource about the DT format, just the library.

All of these should end with full stops or commas. Also I wonder if this needs to be a list, or can be a regular sentence:

The information we can obtain from dtb_stat_node is: its name, and the numbers of children, siblings and properties.

opening curly brace on a new line please :)

some code style preferences: could you indent this line by 1 tab to show its a continuation of the previous statement

I would break the sentence after #size-cells:

and #size-cells. These properties ...

and no need to specify what a cell is, the reader should already be familiar.

I'd reword this a little:

After checking the device tree specification, we know that both properties are encoded as a single cell.

end these with commas/full stops.

opening curly brace on a newline.

underscore missing from function name.

this example is actually wrong: dtb_read_prop_values (like all the other read_prop funcs) returns the number of elements that would be read for a given format. In this case the format is the number of cells.
The output is stored in an array, which is passed to the function as &address_cells in this case. So this example functions only returns the number of #address-cells or #size-cells properties, not their values.

It should look like:

size_t read_cells_property(dtb_node* node, const char* property_name)
{
 dtb_prop* prop = dtb_find_prop(node, property_name);
 if (prop == NULL)
 return 0;
 size_t result = 0;
 if (dtb_read_prop_values(prop, 1, &result) > 0)
 return result;
 return 0;
}

not sure if i made the change requested or not.
And after 4 months i kind of forgot how smoldtb work! Btw can you confirm if i have made or not the change?

change formatting to:

if (node != NULL)
{

missing semicolons

capitalize non-code parts of the title

nice example!

Capitalize start of the sentence.
Also I think the extra space at the start of the first code block can be removed :)

This example is fine, but I think it might better to show reserving space for the returned values on the stack, as is the intended use-case. People can then choose not to use that method if they dont want to.
A lot of the comments here can be moved outside the code too, like assumptions about the global variables and description of the function arguments.
Would also be good to mention why we set the a and b fields of the layout to those values (because those are how each element of the reg property is described in the DT spec).

nice, just a full stop at the end.

Capitalize title