pos, object id

src/js_collections.rs

@@ -161,16 +161,19 @@ impl<T> std::iter::FusedIterator for OwnedArrayIter<T> where T: JsCollectionFrom
 
 impl<T> std::iter::ExactSizeIterator for OwnedArrayIter<T> where T: JsCollectionFromValue {}
 
-/// Represents a reference to an Object ID string held on the javascript heap
-/// and a type that the ID points to.
+/// Represents a reference to an Object ID string in JavaScript memory, typed
+/// according to the object type Rust expects for the object after resolving.
 ///
-/// This representation is less useful on the Rust side due to lack of
-/// visibility on the underlying string and lack of most trait implementations,
-/// and consumes more memory, but is faster to resolve and may be useful with
-/// objects you plan to resolve frequently.
+/// If a value stored in Rust memory is preferred, use [`ObjectId`]; the
+/// JavaScript representation can be harder to work with in Rust code due to
+/// lack of visibility on the underlying string and lack of most trait
+/// implementations, and consumes more memory, but is faster to resolve and may
+/// be useful with objects you plan to resolve frequently.
 ///
 /// This object ID is typed, but not strictly, and can be converted into
 /// referring into another type of object with [`JsObjectId::into_type`].
+///
+/// [`ObjectId`]: crate::local::ObjectId
 // Copy, Clone, Debug, PartialEq, Eq, Hash, PartialEq, Eq implemented manually
 // below
 pub struct JsObjectId<T> {

src/local/object_id.rs

@@ -18,18 +18,15 @@ mod raw;
 pub use errors::*;
 pub use raw::*;
 
-/// Represents an Object ID and a type that the ID points to.
+/// Represents an Object ID and a type that the ID points to, stored in Rust
+/// memory.
 ///
-/// Each object id in screeps is represented by a Mongo GUID, which,
-/// while not guaranteed, is unlikely to change. This takes advantage of that by
-/// storing a packed representation of 12 bytes.
+/// If a reference stored in JavaScript memory is preferred, use [`JsObjectId`].
 ///
-/// This object ID is typed, but not strictly. It's completely safe to create an
-/// ObjectId with an incorrect type, and all operations which use the type will
-/// double-check at runtime.
-///
-/// With that said, using this can provide nice type inference, and should have
-/// few disadvantages to the lower-level alternative, [`RawObjectId`].
+/// Each object id in screeps is represented by an ID of up to 24 hexidemical
+/// characters, which cannot change. This implementation takes advantage of that
+/// by storing a packed representation in a `u128`, using 96 bits for the ID and
+/// 32 bits for tracking the length of the ID string for reconstruction in JS.
 ///
 /// # Conversion
 ///
@@ -55,6 +52,7 @@ pub use raw::*;
 /// accuracy, these ids will be sorted by object creation time.
 ///
 /// [`BTreeMap`]: std::collections::BTreeMap
+/// [`JsObjectId`]: crate::js_collections::JsObjectId
 /// [1]: https://docs.mongodb.com/manual/reference/method/ObjectId/
 // Copy, Clone, Debug, PartialEq, Eq, Hash, PartialEq, Eq implemented manually below
 #[derive(Serialize, Deserialize)]

src/local/position.rs

@@ -20,13 +20,11 @@ mod game_methods;
 mod pair_utils;
 mod world_utils;
 
-/// Represents a position in a particular room in Screeps.
+/// Represents a position in a particular room in Screeps, stored in Rust
+/// memory.
 ///
-/// **Note:** This is analogous to the `RoomPosition` JavaScript type.
-///
-/// We've renamed this type to `Position` in `screeps-game-api` to reflect the
-/// fact that it's implemented entirely as a local type, and does represent a
-/// position located within an entire shard, not only within a single room.
+/// Use [`RoomPosition`] if a reference to an object stored in JavaScript memory
+/// is preferred.
 ///
 /// This should be a very efficient type to use in most if not all situations.
 /// It's represented by a single `u32`, all math operations are implemented in
@@ -112,7 +110,7 @@ mod world_utils;
 ///
 /// # Method Behavior
 ///
-/// While this corresponds with the JavaScript `RoomPosition` type, it is not
+/// While this corresponds with the JavaScript [`RoomPosition`] type, it is not
 /// identical. In particular, all "calculation" methods which take in another
 /// position are re-implemented in pure Rust code, and some behave slightly
 /// different.

src/local/room_coordinate.rs

@@ -175,6 +175,7 @@ impl fmt::Display for RoomCoordinate {
     }
 }
 
+/// An X/Y pair representing a given coordinate relative to any room.
 #[derive(Debug, Default, Hash, Clone, Copy, PartialEq, Eq)]
 pub struct RoomXY {
     pub x: RoomCoordinate,

src/objects/impls/room_position.rs

@@ -15,7 +15,10 @@ use crate::{
 
 #[wasm_bindgen]
 extern "C" {
-    /// An object representing a position in a room.
+    /// An object representing a position in a room, stored in JavaScript
+    /// memory.
+    ///
+    /// Use [`Position`] to store and access the same data in Rust memory.
     ///
     /// [Screeps documentation](https://docs.screeps.com/api/#RoomPosition)
     pub type RoomPosition;