Improve File API related comments

components/net/filemanager_thread.rs

@@ -23,7 +23,7 @@ use util::prefs::PREFS;
 use util::thread::spawn_named;
 use uuid::Uuid;
 
-/// Trait that provider of file-dialog UI should implement.
+/// The provider of file-dialog UI should implement this trait.
 /// It will be used to initialize a generic FileManager.
 /// For example, we can choose a dummy UI for testing purpose.
 pub trait UIProvider where Self: Sync {
@@ -82,8 +82,10 @@ struct FileStoreEntry {
     origin: FileOrigin,
     /// Backend implementation
     file_impl: FileImpl,
-    /// Number of `FileImpl::Sliced` entries in `FileManagerStore`
-    /// that has a reference (FileID) to this entry
+    /// Number of FileID holders that the ID is used to
+    /// index this entry in `FileManagerStore`.
+    /// Reference holders include a FileStoreEntry or
+    /// a script-side File-based Blob
     refs: AtomicUsize,
     /// UUIDs only become valid blob URIs when explicitly requested
     /// by the user with createObjectURL. Validity can be revoked as well.
@@ -157,8 +159,6 @@ impl<UI: 'static + UIProvider> FileManager<UI> {
             FileManagerThreadMsg::DecRef(id, origin, sender) => {
                 if let Ok(id) = Uuid::parse_str(&id.0) {
                     spawn_named("dec ref".to_owned(), move || {
-                        // Since it is simple DecRef (possibly caused by close/drop),
-                        // unset_url_validity is false
                         let _ = sender.send(store.dec_ref(&id, &origin));
                     })
                 } else {
@@ -168,7 +168,6 @@ impl<UI: 'static + UIProvider> FileManager<UI> {
             FileManagerThreadMsg::RevokeBlobURL(id, origin, sender) => {
                 if let Ok(id) = Uuid::parse_str(&id.0) {
                     spawn_named("revoke blob url".to_owned(), move || {
-                        // Since it is revocation, unset_url_validity is true
                         let _ = sender.send(store.set_blob_url_validity(false, &id, &origin));
                     })
                 } else {
@@ -487,8 +486,6 @@ impl <UI: 'static + UIProvider> FileManagerStore<UI> {
             self.remove(id);
 
             if let Some(parent_id) = opt_parent_id {
-                // unset_url_validity for parent is false since we only need
-                // to unset the initial requesting URL
                 return self.dec_ref(&parent_id, origin_in);
             }
         }
@@ -505,7 +502,6 @@ impl <UI: 'static + UIProvider> FileManagerStore<UI> {
                     origin: origin.clone(),
                     file_impl: FileImpl::Memory(blob_buf),
                     refs: AtomicUsize::new(1),
-                    // Valid here since PromoteMemory implies URL creation
                     is_valid_url: AtomicBool::new(set_valid),
                 });
 

components/net_traits/filemanager_thread.rs

@@ -121,17 +121,17 @@ pub struct FilterPattern(pub String);
 
 #[derive(Deserialize, Serialize)]
 pub enum FileManagerThreadMsg {
-    /// Select a single file, return triple (FileID, FileName, lastModified)
+    /// Select a single file. Last field is pre-selected file path for testing
     SelectFile(Vec<FilterPattern>, IpcSender<FileManagerResult<SelectedFile>>, FileOrigin, Option<String>),
 
-    /// Select multiple files, return a vector of triples
+    /// Select multiple files. Last field is pre-selected file paths for testing
     SelectFiles(Vec<FilterPattern>, IpcSender<FileManagerResult<Vec<SelectedFile>>>, FileOrigin, Option<Vec<String>>),
 
-    /// Read file in chunks by FileID, optionally check URL validity based on fourth flag
+    /// Read FileID-indexed file in chunks, optionally check URL validity based on boolean flag
     ReadFile(IpcSender<FileManagerResult<ReadFileProgress>>, SelectedFileId, bool, FileOrigin),
 
     /// Add an entry as promoted memory-based blob and send back the associated FileID
-    /// as part of a valid/invalid Blob URL depending on the second bool flag
+    /// as part of a valid/invalid Blob URL depending on the boolean flag
     PromoteMemory(BlobBuf, bool, IpcSender<Result<SelectedFileId, BlobURLStoreError>>, FileOrigin),
 
     /// Add a sliced entry pointing to the parent FileID, and send back the associated FileID

components/script/dom/blob.rs

@@ -33,17 +33,18 @@ pub struct FileBlob {
 }
 
 
-/// Blob backend implementation
+/// Different backends of Blob
 #[must_root]
 #[derive(JSTraceable)]
 pub enum BlobImpl {
-    /// File-based blob
+    /// File-based blob, whose content lives in the net process
     File(FileBlob),
-    /// Memory-based blob
+    /// Memory-based blob, whose content lives in the script process
     Memory(Vec<u8>),
-    /// Sliced blob, including parent blob and
-    /// relative positions representing current slicing range,
-    /// it is leaf of a two-layer fat tree
+    /// Sliced blob, including parent blob reference and
+    /// relative positions of current slicing range,
+    /// IMPORTANT: The depth of tree is only two, i.e. the parent Blob must be
+    /// either File-based or Memory-based
     Sliced(JS<Blob>, RelativePos),
 }
 
@@ -71,6 +72,7 @@ pub struct Blob {
     reflector_: Reflector,
     #[ignore_heap_size_of = "No clear owner"]
     blob_impl: DOMRefCell<BlobImpl>,
+    /// content-type string
     typeString: String,
     isClosed_: Cell<bool>,
 }
@@ -181,7 +183,7 @@ impl Blob {
 
     /// Promote non-Slice blob:
     /// 1. Memory-based: The bytes in data slice will be transferred to file manager thread.
-    /// 2. File-based: Activation
+    /// 2. File-based: If set_valid, then activate the FileID so it can serve as URL
     /// Depending on set_valid, the returned FileID can be part of
     /// valid or invalid Blob URL.
     fn promote(&self, set_valid: bool) -> SelectedFileId {