docs(core): document several concepts around JsRuntime and ops (#7897)

1 files changed, 33 insertions, 1 deletions

diff --git a/core/resources.rs b/core/resources.rs
index 0a159425c..25ea95f41 100644
--- a/core/resources.rs
+++ b/core/resources.rs
@@ -10,13 +10,21 @@ use std::any::Any;
 use std::collections::HashMap;
 
 /// ResourceId is Deno's version of a file descriptor. ResourceId is also referred
-/// to as rid in the code base.
+/// to as `rid` in the code base.
 pub type ResourceId = u32;
 
 /// These store Deno's file descriptors. These are not necessarily the operating
 /// system ones.
 type ResourceMap = HashMap<ResourceId, (String, Box<dyn Any>)>;
 
+/// Map-like data structure storing Deno's resources (equivalent to file descriptors).
+///
+/// Provides basic methods for element access. A resource can be of any type.
+/// Different types of resources can be stored in the same map, and provided
+/// with a name for description.
+///
+/// Each resource is identified through a _resource ID (rid)_, which acts as
+/// the key in the map.
 #[derive(Default)]
 pub struct ResourceTable {
   map: ResourceMap,
@@ -24,15 +32,22 @@ pub struct ResourceTable {
 }
 
 impl ResourceTable {
+  /// Checks if the given resource ID is contained.
   pub fn has(&self, rid: ResourceId) -> bool {
     self.map.contains_key(&rid)
   }
 
+  /// Returns a shared reference to a resource.
+  ///
+  /// Returns `None`, if `rid` is not stored or has a type different from `T`.
   pub fn get<T: Any>(&self, rid: ResourceId) -> Option<&T> {
     let (_, resource) = self.map.get(&rid)?;
     resource.downcast_ref::<T>()
   }
 
+  /// Returns a mutable reference to a resource.
+  ///
+  /// Returns `None`, if `rid` is not stored or has a type different from `T`.
   pub fn get_mut<T: Any>(&mut self, rid: ResourceId) -> Option<&mut T> {
     let (_, resource) = self.map.get_mut(&rid)?;
     resource.downcast_mut::<T>()
@@ -45,6 +60,12 @@ impl ResourceTable {
     next_rid as ResourceId
   }
 
+  /// Inserts a resource, taking ownership of it.
+  ///
+  /// The resource type is erased at runtime and must be statically known
+  /// when retrieving it through `get()`.
+  ///
+  /// Returns a unique resource ID, which acts as a key for this resource.
   pub fn add(&mut self, name: &str, resource: Box<dyn Any>) -> ResourceId {
     let rid = self.next_rid();
     let r = self.map.insert(rid, (name.to_string(), resource));
@@ -52,6 +73,10 @@ impl ResourceTable {
     rid
   }
 
+  /// Returns a map of resource IDs to names.
+  ///
+  /// The name is the one specified during `add()`. To access resources themselves,
+  /// use the `get()` or `get_mut()` functions.
   pub fn entries(&self) -> HashMap<ResourceId, String> {
     self
       .map
@@ -66,6 +91,13 @@ impl ResourceTable {
     self.map.remove(&rid).map(|(_name, _resource)| ())
   }
 
+  /// Removes the resource identified by `rid` and returns it.
+  ///
+  /// When the provided `rid` is stored, the associated resource will be removed.
+  /// Otherwise, nothing happens and `None` is returned.
+  ///
+  /// If the type `T` matches the resource's type, the resource will be returned.
+  /// If the type mismatches, `None` is returned, but the resource is still removed.
   pub fn remove<T: Any>(&mut self, rid: ResourceId) -> Option<Box<T>> {
     if let Some((_name, resource)) = self.map.remove(&rid) {
       let res = match resource.downcast::<T>() {