[ROOT-5157] Enhance Documentation for I/O customization rules

Explain what you would like to see improved and how.

From https://its.cern.ch/jira/browse/ROOT-5157

Chapter on schema evolution support needs to be added to the Users' Guide. For example bases in the scenario:

class Position { /* point in 3D space */
 public:
  Position(float x, float y, float z);
  // get Cartesian coordinates
  float x();
  float y();
  float z();
  // get spherical coordinates
  float r();
  float phi();
  float theta();
  // get pseudorapidity
  float eta();
};

class Hit : public Position { /* localized detector signal */
 public:
  Hit(float energy, float x, float y, float z);
  // get energy and transverse energy
  float e();
  float et();
};

Now, consider 3 stages of evolution for Position:

Simplest implementation is to have Cartesian coordinates as private attributes;
The users find that they most often use radius and azimuth, hence decide to store spherical coordinates instead of (x,y,z);
Actually, colliders use eta more often than theta, so that the internal state is now given by (r, phi, eta).

In parallel and independently, Hit also evolves:

a. Simplest implementation is to have only the energy as private member;

b. Because the number of requests for the transverse energy is very high, the users want to optimize the speed by keeping Et as private member;

c. Well, it happens that disk space is short and e() is rarely called, so that it makes sense to reduce the size of the Hit class by dropping the energy member and computing the energy just when calling the method e(). They also found that the detector parameters used to store data in version b are wrong, so that one needs to scale the energy by 1.3 only for version b (a and c are correct).

Could you please provide a working example in which data are saved and fetched with different combinations of (1, 2, 3)x(a, b, c) (at least with 1a, 2b, 3c)?

The next step is to consider collections of objects:

i) define

class Track { /* particle trajectory */

 private:
  std::vector< Hit > m_hits;

};

ii) Because the crazy developers of Hit decided to make such class variable size, one needs to store a vector of pointers instead of objects:

class Track { /* particle trajectory */

 private:
  std::vector< Hit* > m_hits;

};

iii) Disk space is very short! We cannot waste the single 32-bits word used by the STL vector...

class Track { /* particle trajectory */

 private:
  unsigned int m_Nhits;
  Hit* m_hits;          //[m_Nhits]

};

Please, provide some working example that shows how to write and read all these 3 evolutions of Track (you may use whatever version of Hits).

[Courtesy of Diego Casadei]

ROOT version

Any

Installation method

Any

Operating system

Any

Additional context

No response

root-project / root