[skip-ci][rfile] add more documentation to RFile class

Author: silverweed

io/io/inc/ROOT/RFile.hxx

@@ -34,7 +34,66 @@ ROOT::RLogChannel &RFileLog();
 \ingroup RFile
 \brief An interface to read from, or write to, a ROOT file, as well as performing other common operations.
 
-TODO: more in-depth explanation
+## When and why should you use RFile
+
+RFile is a modern and minimalistic interface to ROOT files, both local and remote, that can be used instead of TFile
+when the following conditions are met:
+- you want a simple interface that makes it easy to do things right and hard to do things wrong;
+- you only need basic Put/Get operations and don't need the more advanced TFile/TDirectory functionalities;
+- you want more robustness and better error reporting for those operations;
+- you want clearer ownership semantics expressed through the type system rather than having objects "automagically"
+  handled for you via implicit ownership of raw pointers.
+
+RFile doesn't try to cover the entirety of use cases covered by TFile/TDirectory/TDirectoryFile and is not
+a 1:1 replacement for them. It is meant to simplify the most common use cases and make them easier to handle by
+minimizing the amount of ROOT-specific quirks and conforming to more standard C++ practices.
+
+## Ownership model
+
+RFile handles ownership via smart pointers, typically std::unique_ptr.
+
+When getting an object from the file (via RFile::Get) you get back a unique copy of the object. Calling `Get` on the
+same object twice produces two independent clones of the object. The ownership over that object is solely on the caller
+and not shared with the RFile. Therefore, the object will remain valid after closing or destroying the RFile that
+generated it. This also means that any modification done to the object are **not** reflected to the file automatically:
+to update the object in the file you need to write it again (via RFile::Overwrite).
+
+RFile::Put and RFile::Overwrite are the way to write objects to the file. Both methods take a const reference to the
+object to write and don't change the ownership of the object in any way. Calling Put or Overwrite doesn't guarantee that
+the object is immediately written to the underlying storage: to ensure that, you need to call RFile::Flush (or close the
+file).
+
+## Directories
+
+Differently from TFile, the RFile class itself is not also a "directory". In fact, there is no RDirectory class at all.
+
+Directories are still an existing concept in RFile (since they are a concept in the ROOT binary format),
+but they are usually interacted with indirectly, via the use of filesystem-like string-based paths. If you Put an object
+in an RFile under the path "path/to/object", "object" will be stored under directory "to" which is in turn stored under
+directory "path". This hierarchy is encoded in the ROOT file itself and it can provide some optimization and/or
+conveniencies when querying objects.
+
+For the most part, it is convenient to think about RFile in terms of a key-value storage where string-based paths are
+used to refer to arbitrary objects. However, given the hierarchical nature of ROOT files, certain filesystem-like
+properties are applied to paths, for ease of use: the '/' character is treated specially as the directory separator;
+multiple '/' in a row are collapsed into one (since RFile doesn't allow directories with empty names).
+
+At the moment, RFile doesn't allow getting directories via Get, nor writing ones via Put (this may change in the
+future).
+
+## Sample usage
+Opening an RFile (for writing) and writing an object to it:
+~~~{.cpp}
+auto rfile = ROOT::RFile::Recreate("my_file.root");
+auto myObj = TH1D("h", "h", 10, 0, 1);
+rfile->Put(myObj.GetName(), myObj);
+~~~
+
+Opening an RFile (for reading) and reading an object from it:
+~~~{.cpp}
+auto rfile = ROOT::RFile::Open("my_file.root");
+auto myObj = file->Get<TH1D>("h");
+~~~
 */
 class RFile final {
    enum PutFlags {