Add thorough documentation to helper functions and structs

[raccog]

Hello, I've been implementing a UEFI bootloader in Rust and really enjoy how this project is turning out! I was wondering if I could help contribute to the documentation, as there are some functions and structs that I feel could be better documented.

For example, I think it would be nice if helper functions like get_image_file_system() would describe both the possible errors that can occur and also which UEFI interfaces/functions are used. As helper functions like this are not described in the UEFI specification, it would be nice to be able to look at the crate documentation for detailed information.

I also think that adding documentation on how to get an instance of each struct would be helpful, too. For example, the struct BootServices can be retrieved by calling boot_services() on SystemTable. Although examples such as this are described in the UEFI spec, it would be convenient to provide a link to boot_services() from BootService's documentation. Another example is to provide a link to get_image_file_system() and locate_device_path() (and other functions that can return a SimpleFileSystem) in SimpleFileSystem's documentation.

I was also going to suggest adding documentation for why protocols are wrapped in UnsafeCell, but from the most recent commit, it seems like this is already covered!

[nicholasbishop]

Hi, thanks for filing this issue. Contributions to documentation are definitely very welcome! I think the examples you give of places that could use additional documentation and intra-doc links all sound like good additions.

[raccog]

I just added a small amount of documentation that links BootServices to boot_services() and RuntimeServices to runtime_services().

I plan on slowly adding more documentation where I think it would be beneficial in the crate. Should I make a single pull request for each documentation change, or should I wait until I have more substantial changes to make a larger pull request?

[GabrielMajeri]

@raccog Thanks!

I plan on slowly adding more documentation where I think it would be beneficial in the crate. Should I make a single pull request for each documentation change, or should I wait until I have more substantial changes to make a larger pull request?

As you prefer. In theory, individual PRs are easier to review, but if you keep each commit atomic and with a relevant title, then the effort would be the same for us.

[raccog]

@GabrielMajeri Great! I'll submit a small PR to start off and then go from there.

[phip1611]

I think we fixed this. Feel free to re-open if something is missing with specific pointers. Thanks!