Uploaded image for project: 'ROOT'
  1. ROOT
  2. ROOT-3798

The various TTree::Branch functions are very hard to figure out

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Open (View Workflow)
    • Priority: Medium
    • Resolution: Unresolved
    • Affects Version/s: < v5-28-00
    • Fix Version/s: None
    • Component/s: I/O
    • Labels:
      None
    • Environment:

      All

      Description

      I have been trying to figure out what all of the various TTree::Branch functions do, but I am baffled. In the automatically generated web documentation, nine TTree::Branch function prototypes appear near the top of the page documenting TTree:

      [1] virtual Int_t Branch(TList* list, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [2] virtual Int_t Branch(const char* folder, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [] virtual Int_t Branch(TCollection* list, Int_t bufsize = 32000, Int_t splitlevel = 99, const char* name = &quot;&quot
      [3] virtual TBranch* Branch(const char* name, void* address, const char* leaflist, Int_t bufsize = 32000)
      [4] TBranch* Branch(const char* name, char* address, const char* leaflist, Int_t bufsize = 32000)
      [5] TBranch* Branch(const char* name, long address, const char* leaflist, Int_t bufsize = 32000)
      [6] TBranch* Branch(const char* name, int address, const char* leaflist, Int_t bufsize = 32000)
      [8] TBranch* Branch(const char* name, void** obj, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [7] TBranch* Branch(const char* name, const char* classname, void** obj, Int_t bufsize = 32000, Int_t splitlevel = 99)

      I have prefixed them with the number that appears at the end of the HTML link to the documentation. Note that the one between [2] and [3] has no number. In the documenation below, only some of these functions appear:

      [1] Int_t Branch(TList* list, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [2] Int_t Branch(const char* folder, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [] Int_t Branch(TCollection* list, Int_t bufsize = 32000, Int_t splitlevel = 99, const char* name = &quot;&quot
      [3] TBranch* Branch(const char* name, void* address, const char* leaflist, Int_t bufsize = 32000)
      [7] TBranch* Branch(const char* name, const char* classname, void** obj, Int_t bufsize = 32000, Int_t splitlevel = 99)

      Clicking on the others does not take you anywhere, nor do they appear below in some unlinked form.

      Looking at the actual header file tree/tree/inc/TTree.h, I see 11 TTree::Branch functions, some of which match the documentation above, but most of which don't appear at all. Most of the ones in the documenation don't appear here, either.

      [] virtual Int_t Branch(TCollection* list, Int_t bufsize = 32000, Int_t splitlevel = 99, const char* name = &quot;&quot;
      [1] virtual Int_t Branch(TList* list, Int_t bufsize = 32000, Int_t splitlevel = 99);
      [2] virtual Int_t Branch(const char* folder, Int_t bufsize = 32000, Int_t splitlevel = 99);
      [4] virtual TBranch Branch(const char name, void* address, const char* leaflist, Int_t bufsize = 32000);
      [new] TBranch Branch(const char name, long address, const char* leaflist, Int_t bufsize = 32000)
      [new] TBranch Branch(const char name, int address, const char* leaflist, Int_t bufsize = 32000)
      [new] virtual TBranch Branch(const char name, const char* classname, void* addobj, Int_t bufsize = 32000, Int_t splitlevel = 99);
      [new] template &lt;class T&gt; TBranch Branch(const char name, const char* classname, T* obj, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [new] template &lt;class T&gt; TBranch Branch(const char name, const char* classname, T** addobj, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [new] template &lt;class T&gt; TBranch Branch(const char name, T** addobj, Int_t bufsize = 32000, Int_t splitlevel = 99)
      [new] template &lt;class T&gt; TBranch Branch(const char name, T* obj, Int_t bufsize = 32000, Int_t splitlevel = 99)

      I assume that the use of templates and/or mixing declarations and definitions in the header file and/or preprocessor macros in the header file has confused the automatic documentation generator. It looks like some sort of variable name translation is going on which makes it extremely difficult for the reader to figure out which function in the documentation matches up with which function in the source itself.

      The general documentation at the top of TTree.cxx and the web class reference only covers a few cases, and even its treatment of these is rather muddled. For instance, &quot;Case C&quot; at line 107 and following in TTree.cxx circularly references itself when it says &quot;In case the object member is a TClonesArray, the mechanism described in case C is applied to this array.&quot; The User's Guide also only covers a few cases.

      All in all, the situation is such that I cannot even figure out what function is being called on line 33 of tutorials/tree/tcl.C, which prompted me to start this investigation. Certainly there is no Branch(char *, TClonesArray **, int, Int_t). I suppose it must be
      template &lt;class T&gt; TBranch Branch(const char name, T** addobj, Int_t bufsize = 32000, Int_t splitlevel = 99) with T==TClonesArray. This is one of the functions that does not appear at all in the web documentation.

      So there are multiple problems here:

      • There are too many TTree::Branch functions
      • Clear human-written documentation is unclear or does not exist for most forms of TTree::Branch
      • The automatic web documentation generator fails to generate documentation for most forms of TTree::Branch

      If I understood enough of what was going on, I'd attempt to write the documentation, but I'm afraid that I am too confused for that. However, if a start could be made at cleaning this all up, I would be happy to help continue the work.

      Thanks,
      Matthew

        Attachments

          Activity

            People

            Assignee:
            pcanal Philippe Canal
            Reporter:
            strait Jim Strait
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Dates

              Created:
              Updated: