[skip-ci][ntuple] Add doc comment to RNTupleReader::GetNEntries()

Author: silverweed

tree/ntuple/inc/ROOT/RNTupleReader.hxx

@@ -171,6 +171,21 @@ public:
    }
    ~RNTupleReader();
 
+   /// Returns the number of entries in this RNTuple.
+   /// \attention This method requires locking a mutex, therefore it can become relatively expensive to call repeatedly
+   /// (even in the absence of contention). Unless necessary, you should not call this method in the condition of a
+   /// `for` loop. Instead, either call it once and cache the result, use the faster `GetEntryRange()` or, equivalently,
+   /// use the RNTupleReader directly as an iterator.
+   ///
+   /// ~~~ {.cpp}
+   /// // BAD for performance:
+   /// for (auto i = 0u; i < reader->GetNEntries(); ++i) { ... }
+   ///
+   /// // GOOD for performance (all equivalent):
+   /// for (auto i = 0u, n = reader->GetNEntries(); i < n; ++i) { ... }
+   /// for (auto i : reader->GetEntryRange()) { ... }
+   /// for (auto i : *reader) { ... }
+   /// ~~~
    ROOT::NTupleSize_t GetNEntries() const { return fSource->GetNEntries(); }
    const ROOT::RNTupleModel &GetModel();
    std::unique_ptr<ROOT::REntry> CreateEntry();