[ntuple] Improve documentation of RNTupleParallelWriter

Author: hahnjo

tree/ntuple/inc/ROOT/RNTupleFillContext.hxx

@@ -172,7 +172,7 @@ public:
 
    void EnableMetrics() { fMetrics.Enable(); }
    const Detail::RNTupleMetrics &GetMetrics() const { return fMetrics; }
-}; // class RNTupleFillContext
+};
 
 } // namespace Experimental
 } // namespace ROOT

tree/ntuple/inc/ROOT/RNTupleFillStatus.hxx

@@ -30,8 +30,8 @@ class RNTupleFillContext;
 \ingroup NTuple
 \brief A status object after filling an entry
 
-After passing an instance to RNTupleWriter::FillNoFlush or RNTupleFillContext::FillNoFlush, the caller must check
-ShouldFlushCluster and call RNTupleWriter::FlushCluster or RNTupleFillContext::FlushCluster if necessary.
+After passing an instance to RNTupleWriter::FillNoFlush() or RNTupleFillContext::FillNoFlush(), the caller must check
+ShouldFlushCluster() and call RNTupleWriter::FlushCluster() or RNTupleFillContext::FlushCluster() if necessary.
 */
 // clang-format on
 class RNTupleFillStatus {
@@ -55,7 +55,7 @@ public:
    std::size_t GetLastEntrySize() const { return fLastEntrySize; }
    /// Return true if the caller should call FlushCluster.
    bool ShouldFlushCluster() const { return fShouldFlushCluster; }
-}; // class RNTupleFillContext
+};
 
 } // namespace ROOT
 

tree/ntuple/inc/ROOT/RNTupleParallelWriter.hxx

@@ -44,20 +44,19 @@ class RNTupleFillContext;
 \brief A writer to fill an RNTuple from multiple contexts
 
 Compared to the sequential RNTupleWriter, a parallel writer enables the creation of multiple RNTupleFillContext (see
-RNTupleParallelWriter::CreateFillContext).  Each fill context prepares independent clusters that are appended to the
-common ntuple with internal synchronization.  Before destruction, all fill contexts must have flushed their data and
-been destroyed (or data could be lost!).
+CreateFillContext()).  Each fill context prepares independent clusters that are appended to the common RNTuple with
+internal synchronization.  Before destruction, all fill contexts must have flushed their data and been destroyed (or
+data could be lost!).
 
-For user convenience, RNTupleParallelWriter::CreateFillContext is thread-safe and may be called from multiple threads
-in parallel at any time, also after some data has already been written.  Internally, the original model is cloned and
-ownership is passed to a newly created RNTupleFillContext.  For that reason, it is recommended to use
-RNTupleModel::CreateBare when creating the model for parallel writing and avoid the allocation of a useless default
-REntry per context.
+For user convenience, CreateFillContext() is thread-safe and may be called from multiple threads in parallel at any
+time, also after some data has already been written.  Internally, the original model is cloned and ownership is passed
+to a newly created RNTupleFillContext.  For that reason, it is recommended to use RNTupleModel::CreateBare when creating
+the model for parallel writing and avoid the allocation of a useless default REntry per context.
 
 Note that the sequence of independently prepared clusters is indeterminate and therefore entries are only partially
 ordered:  Entries from one context are totally ordered as they were filled.  However, there is no orderering with other
-contexts and the entries may be appended to the ntuple either before or after other entries written in parallel into
-other contexts.  In addition, two consecutive entries in one fill context can end up separated in the final ntuple, if
+contexts and the entries may be appended to the RNTuple either before or after other entries written in parallel into
+other contexts.  In addition, two consecutive entries in one fill context can end up separated in the final RNTuple, if
 they happen to fall onto a cluster boundary and other contexts append more entries before the next cluster is full.
 
 At the moment, the parallel writer does not (yet) support incremental updates of the underlying model. Please refer to
@@ -82,11 +81,17 @@ private:
    RNTupleParallelWriter &operator=(const RNTupleParallelWriter &) = delete;
 
 public:
-   /// Recreate a new file and return a writer to write an ntuple.
+   /// Recreate a new file and return a writer to write an RNTuple.
    static std::unique_ptr<RNTupleParallelWriter>
    Recreate(std::unique_ptr<ROOT::RNTupleModel> model, std::string_view ntupleName, std::string_view storage,
             const ROOT::RNTupleWriteOptions &options = ROOT::RNTupleWriteOptions());
-   /// Append an ntuple to the existing file, which must not be accessed while data is filled into any created context.
+   /// Append an RNTuple to the existing file.
+   ///
+   /// While the writer synchronizes between multiple fill contexts created from the same writer, there is no
+   /// synchronization with other writers or other clients that write into the same file. The caller must ensure that
+   /// the underlying file is not be accessed while data is filled into any created context. To improve performance, it
+   /// is allowed to use special methods that are guaranteed to not interact with the underlying file, such as
+   /// RNTupleFillContext::FillNoFlush().
    static std::unique_ptr<RNTupleParallelWriter>
    Append(std::unique_ptr<ROOT::RNTupleModel> model, std::string_view ntupleName, TDirectory &fileOrDirectory,
           const ROOT::RNTupleWriteOptions &options = ROOT::RNTupleWriteOptions());
@@ -97,7 +102,7 @@ public:
    /// thread-safe and may be called from multiple threads in parallel at any time, also after some data has already
    /// been written.
    ///
-   /// Note that all fill contexts must be destroyed before RNTupleParallelWriter::CommitDataset() is called.
+   /// Note that all fill contexts must be destroyed before CommitDataset() is called.
    std::shared_ptr<RNTupleFillContext> CreateFillContext();
 
    /// Automatically called by the destructor