Added long doc comment for Filesystem storage type

src/mailstore/filesystem.rs

@@ -33,6 +33,43 @@ pub trait MultiDomain: MailStore {
     ) -> Result<(), <Self as filesystem::MultiDomain>::Error>;
 }
 
+/// The Filestore storage backend uses the filesystem to map folders to domains,
+/// mail users and folders of messages. It can also be used as a `ClientCertificateStore`.
+/// The layout of files inside a filesystem mailstore is as below.
+/// ```Sh
+/// test/mailstore/
+/// └── misfin.example.org
+///     ├── dick
+///     │   ├── Inbox
+///     │   │   ├── 619310.gmi
+///     │   │   └── 868379.gmi
+///     │   ├── blurb
+///     │   └── certificate.pem
+///     └── jane
+///         ├── Inbox
+///         │   ├── 252366.gmi
+///         │   └── 654064.gmi
+///         ├── blurb
+///         └── certificate.pem
+/// ```
+/// In this made up example the Misfin server in question serves the domain
+/// "misfin.example.org", which has the users "dick" and "jane", whose mailbox
+/// addresses would be "dick@misfin.example.org" and "jane@misfin.example.org".
+/// Within each account folder any subfolders are to be considered as mail folders,
+/// with the default folder for delivering new mail being "Inbox". The "blurb"
+/// file (optional) contains the display name of the user, and their client
+/// certificate is stored in pem-encoded ascii armor format in "certificate.pem",
+/// if the `Filesystem` is also to be used as a `ClientCertificateStore`.
+///
+/// The permissions on each individual account folder are set to 0o2700 at the
+/// time of creation, such that the folder is read/write for the user and group
+/// and any entries created within will have the same group membership. If the
+/// username of the account corresponds to a group name on the system, and the
+/// user which the server runs as is a member of this group, then said group will
+/// own the directory. In this way the server will be able to write incoming
+/// mail into the folder and the user will be able to read and manage their
+/// folders and messages, without being able to see any other user's mail and
+/// without the server requiring elevated privileges.
 #[derive(Clone, Debug)]
 #[cfg_attr(feature = "serde", derive(Deserialize, Serialize))]
 pub struct Filesystem {