doc: improve uefi::boot::memory_map() documentation

Author: phip1611

uefi/src/boot.rs

@@ -245,7 +245,13 @@ pub(crate) fn memory_map_size() -> MemoryMapMeta {
 }
 
 /// Stores the current UEFI memory map in an UEFI-heap allocated buffer
-/// and returns a [`MemoryMapOwned`].
+/// and returns a [`MemoryMapOwned`]. 
+/// 
+/// The implementation tries to mitigate some UEFI pitfalls, such as getting
+/// the right allocation size for the memory map to prevent
+/// [`Status::BUFFER_TOO_SMALL`]. If [`Status::BUFFER_TOO_SMALL`] is returned, 
+/// further calls are likely to fail as well. If so, the situation may be
+/// considered as unrecoverable error.
 ///
 /// # Parameters
 ///