Extend some doccomments based on Github discussions #1237
Conversation
vi
force-pushed
the
doc_fixes
branch
2 times, most recently
from
e90ae89
to
7931f21
Compare
src/tree.rs
Outdated
| @@ -335,6 +337,9 @@ impl Tree { | |||
| /// assert_eq!(&processed.get(b"k3").unwrap().unwrap(), b"yappin' ligers"); | |||
| /// # Ok(()) } | |||
| /// ``` | |||
| /// | |||
| /// Note simple string prepeding in the example above should be natively changed | |||
| /// to some complex operation, as transactions may be tried multiple times. | |||
There was a problem hiding this comment.
incorrect. transactions are serializable.
There was a problem hiding this comment.
Shall I try to construct some concrete example (involving external I/O from within a transaction) where this break down?
src/lib.rs
Outdated
| //! Sled is not designed to be used by multiple processes simultaneously. | ||
| //! Although Sled tries to use advisory filesystem locking to | ||
| //! protect the database from accidental access from foreign | ||
| //! processes, this should not be reiled upon. |
There was a problem hiding this comment.
Where should it be instead?
I don't see other mentions of the shared multiprocess use cases in the documentation, yet questions do arise.
There was a problem hiding this comment.
I've reworded this and placed it high up on the main README 66cf957
src/db.rs
Outdated
| @@ -5,6 +5,9 @@ use crate::*; | |||
| /// The `sled` embedded database! Implements | |||
| /// `Deref<Target = sled::Tree>` to refer to | |||
| /// a default keyspace / namespace / bucket. | |||
| /// | |||
| /// Note that dropping `Db` does not gurantee closing the database. | |||
| /// Sled may still access the underlying directory under the hood. | |||
There was a problem hiding this comment.
Where should it be (assuming the comment itself is not wrong, just misplaced)?
Filesystem usage aspect may be important for users, especially, for example, if the same process manages mounts/unmounts of the filesystem that backs the database.
src/tree.rs
Outdated
| @@ -231,6 +231,8 @@ impl Tree { | |||
|
|
|||
| /// Perform a multi-key serializable transaction. | |||
| /// | |||
| /// User-provided function `f` may be run multiple times in case of conflicts. | |||
| /// | |||
There was a problem hiding this comment.
please get rid of all of the other comments except this one, which is the only one we discussed earlier.
|
Apologies for my harsh tone. I was feeling a bit frustrated at the feeling that I have been repeating the same thing, but better docs are a great way to address this frustration. I've reworded a few of your comments and placed them in places I hope will be visible to people who will encounter them. 66cf957 |
Addresses:
sled::Db. #1234finsled::Db::transaction. #1235