From 3f6ffef9f375f8b27d1325fa5dd13f19fb07de90 Mon Sep 17 00:00:00 2001
From: Eryn Wells <eryn@erynwells.me>
Date: Fri, 8 Mar 2024 08:15:45 -0800
Subject: [PATCH] [bitboard] Write some documentation; mark some methods const

- Implement BitBoard::is_populated(), the opposite of ::is_empty()
- Write a bit of documentation for the BitBoard Library and for some methods on BitBoard
- Mark a few methods as const
---
 bitboard/src/bitboard.rs | 35 ++++++++++++++++++++++++++++++-----
 bitboard/src/library.rs  |  8 ++++++++
 2 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/bitboard/src/bitboard.rs b/bitboard/src/bitboard.rs
index 8d8d8dc..5efbed0 100644
--- a/bitboard/src/bitboard.rs
+++ b/bitboard/src/bitboard.rs
@@ -67,16 +67,41 @@ impl BitBoard {
 }
 
 impl BitBoard {
-    pub fn as_bits(&self) -> &u64 {
+    pub const fn as_bits(&self) -> &u64 {
         &self.0
     }
 
-    pub fn is_empty(&self) -> bool {
+    /// Returns `true` if the [`BitBoard`] has no bits set.
+    ///
+    /// ## Examples
+    ///
+    /// ```
+    /// use chessfriend_bitboard::BitBoard;
+    /// assert!(BitBoard::EMPTY.is_populated());
+    /// assert!(!BitBoard::FULL.is_populated());
+    /// assert!(!BitBoard::new(0b1000).is_populated());
+    /// ```
+    pub const fn is_empty(&self) -> bool {
         self.0 == 0
     }
 
-    pub fn is_set(self, sq: Square) -> bool {
-        let square_bitboard: BitBoard = sq.into();
+    /// Returns `true` if the [`BitBoard`] has at least one bit set.
+    ///
+    /// ## Examples
+    ///
+    /// ```
+    /// use chessfriend_bitboard::BitBoard;
+    /// assert!(!BitBoard::EMPTY.is_populated());
+    /// assert!(BitBoard::FULL.is_populated());
+    /// assert!(BitBoard::new(0b1).is_populated());
+    /// ```
+    pub const fn is_populated(&self) -> bool {
+        self.0 != 0
+    }
+
+    /// Returns `true` if this [`BitBoard`] has the bit corresponding to `square` set.
+    pub fn is_set(self, square: Square) -> bool {
+        let square_bitboard: BitBoard = square.into();
         !(self & square_bitboard).is_empty()
     }
 
@@ -90,7 +115,7 @@ impl BitBoard {
     /// assert_eq!(BitBoard::new(0b01011110010).population_count(), 6);
     /// assert_eq!(BitBoard::FULL.population_count(), 64);
     /// ```
-    pub fn population_count(&self) -> u32 {
+    pub const fn population_count(&self) -> u32 {
         self.0.count_ones()
     }
 
diff --git a/bitboard/src/library.rs b/bitboard/src/library.rs
index 5e74259..f87084b 100644
--- a/bitboard/src/library.rs
+++ b/bitboard/src/library.rs
@@ -1,5 +1,13 @@
 // Eryn Wells <eryn@erynwells.me>
 
+//! # The BitBoard Library
+//!
+//! This module implements a collection of commonly used BitBoards that can be
+//! looked up efficiently as needed.
+//!
+//! The `library()` method returns a static instance of a `Library`, which
+//! provides getters for all available BitBoards.
+
 use crate::BitBoard;
 use chessfriend_core::{Color, Direction, Square};
 use std::sync::OnceLock;