libbpf-rs: Add more doc comments

I only added comments where I was pretty sure I was right. Better to be
low on docs than have wrong docs. For the stuff I didn't know I applied
localized lint suppression.

Done b/c next commit will trigger more missing doc warnings.

libbpf-rs/src/map.rs

@@ -125,10 +125,14 @@ impl<'obj> OpenMapMut<'obj> {
         }
     }
 
+    /// Bind map to a particular network device.
+    ///
+    /// Used for offloading maps to hardware.
     pub fn set_map_ifindex(&mut self, idx: u32) {
         unsafe { libbpf_sys::bpf_map__set_ifindex(self.ptr.as_ptr(), idx) };
     }
 
+    /// Set the initial value of the map.
     pub fn set_initial_value(&mut self, data: &[u8]) -> Result<()> {
         let ret = unsafe {
             libbpf_sys::bpf_map__set_initial_value(
@@ -141,53 +145,68 @@ impl<'obj> OpenMapMut<'obj> {
         util::parse_ret(ret)
     }
 
+    /// Set the type of the map.
     pub fn set_type(&mut self, ty: MapType) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_type(self.ptr.as_ptr(), ty as u32) };
         util::parse_ret(ret)
     }
 
+    /// Set the key size of the map in bytes.
     pub fn set_key_size(&mut self, size: u32) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_key_size(self.ptr.as_ptr(), size) };
         util::parse_ret(ret)
     }
 
+    /// Set the value size of the map in bytes.
     pub fn set_value_size(&mut self, size: u32) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_value_size(self.ptr.as_ptr(), size) };
         util::parse_ret(ret)
     }
 
+    /// Set the maximum number of entries this map can have.
     pub fn set_max_entries(&mut self, count: u32) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_max_entries(self.ptr.as_ptr(), count) };
         util::parse_ret(ret)
     }
 
+    /// Set flags on this map.
     pub fn set_map_flags(&mut self, flags: u32) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_map_flags(self.ptr.as_ptr(), flags) };
         util::parse_ret(ret)
     }
 
+    // TODO: Document member.
+    #[allow(missing_docs)]
     pub fn set_numa_node(&mut self, numa_node: u32) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_numa_node(self.ptr.as_ptr(), numa_node) };
         util::parse_ret(ret)
     }
 
+    // TODO: Document member.
+    #[allow(missing_docs)]
     pub fn set_inner_map_fd(&mut self, inner_map_fd: BorrowedFd<'_>) -> Result<()> {
         let ret = unsafe {
             libbpf_sys::bpf_map__set_inner_map_fd(self.ptr.as_ptr(), inner_map_fd.as_raw_fd())
         };
         util::parse_ret(ret)
     }
 
+    // TODO: Document member.
+    #[allow(missing_docs)]
     pub fn set_map_extra(&mut self, map_extra: u64) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_map_extra(self.ptr.as_ptr(), map_extra) };
         util::parse_ret(ret)
     }
 
+    /// Set whether or not libbpf should automatically create this map during load phase.
     pub fn set_autocreate(&mut self, autocreate: bool) -> Result<()> {
         let ret = unsafe { libbpf_sys::bpf_map__set_autocreate(self.ptr.as_ptr(), autocreate) };
         util::parse_ret(ret)
     }
 
+    /// Set where the map should be pinned.
+    ///
+    /// Note this does not actually create the pin.
     pub fn set_pin_path<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
         let path_c = util::path_to_cstring(path)?;
         let path_ptr = path_c.as_ptr();

libbpf-rs/src/program.rs

@@ -123,8 +123,6 @@ pub struct OpenProgramImpl<'obj, T = ()> {
     _phantom: PhantomData<&'obj T>,
 }
 
-// TODO: Document variants.
-#[allow(missing_docs)]
 impl<'obj> OpenProgram<'obj> {
     /// Create a new [`OpenProgram`] from a ptr to a `libbpf_sys::bpf_program`.
     pub fn new(prog: &'obj libbpf_sys::bpf_program) -> Self {
@@ -136,7 +134,7 @@ impl<'obj> OpenProgram<'obj> {
         }
     }
 
-    // The `ProgramType` of this `OpenProgram`.
+    /// The `ProgramType` of this `OpenProgram`.
     pub fn prog_type(&self) -> ProgramType {
         ProgramType::from(unsafe { libbpf_sys::bpf_program__type(self.ptr.as_ptr()) })
     }
@@ -194,18 +192,23 @@ impl<'obj> OpenProgramMut<'obj> {
         }
     }
 
+    /// Set the program type.
     pub fn set_prog_type(&mut self, prog_type: ProgramType) {
         let rc = unsafe { libbpf_sys::bpf_program__set_type(self.ptr.as_ptr(), prog_type as u32) };
         debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
     }
 
+    /// Set the attachment type of the program.
     pub fn set_attach_type(&mut self, attach_type: ProgramAttachType) {
         let rc = unsafe {
             libbpf_sys::bpf_program__set_expected_attach_type(self.ptr.as_ptr(), attach_type as u32)
         };
         debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
     }
 
+    /// Bind the program to a particular network device.
+    ///
+    /// Currently only used for hardware offload and certain XDP features such like HW metadata.
     pub fn set_ifindex(&mut self, idx: u32) {
         unsafe { libbpf_sys::bpf_program__set_ifindex(self.ptr.as_ptr(), idx) }
     }
@@ -230,6 +233,7 @@ impl<'obj> OpenProgramMut<'obj> {
         debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
     }
 
+    #[allow(missing_docs)]
     pub fn set_attach_target(
         &mut self,
         attach_prog_fd: i32,
@@ -257,6 +261,7 @@ impl<'obj> OpenProgramMut<'obj> {
         util::parse_ret(ret)
     }
 
+    /// Set flags on the program.
     pub fn set_flags(&mut self, flags: u32) {
         let rc = unsafe { libbpf_sys::bpf_program__set_flags(self.ptr.as_ptr(), flags) };
         debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
@@ -600,6 +605,7 @@ impl<'obj> Program<'obj> {
     }
 
     #[deprecated = "renamed to Program::fd_from_id"]
+    #[allow(missing_docs)]
     #[inline]
     pub fn get_fd_by_id(id: u32) -> Result<OwnedFd> {
         Self::fd_from_id(id)
@@ -617,6 +623,7 @@ impl<'obj> Program<'obj> {
 
     // TODO: Remove once 0.25 is cut.
     #[deprecated = "renamed to Program::id_from_fd"]
+    #[allow(missing_docs)]
     #[inline]
     pub fn get_id_by_fd(fd: BorrowedFd<'_>) -> Result<u32> {
         Self::id_from_fd(fd)