Skip to content

[io] Remove non-user related doc from TFile class. [skip-ci] #9616

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

[io] Remove non-user related doc from TFile class. [skip-ci] #9616

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 5 additions & 56 deletions io/io/src/TFile.cxx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,67 +9,16 @@
* For the list of contributors see $ROOTSYS/README/CREDITS. *
*************************************************************************/

/**
\defgroup IO Input/Output Library

The library collecting the ROOT classes dedicated to data input and output.

The detailed internal description of the \ref rootio is available.
*/

/**
\file TFile.cxx
\class TFile
\ingroup IO

A ROOT file is a suite of consecutive data records (TKey instances) with
a well defined format.

If the key is located past the 32 bit file limit (> 2 GB) then some fields will
Copy link
Member

@pcanal pcanal Jan 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This information is "essential" developer and advancer user information and belong in the repository (as it can and has evolved). There should be an explicit link or reference to where in the repository that information lives.

Copy link
Member Author

@Axel-Naumann Axel-Naumann Jan 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's referenced as \sa \ref rootio, see https://root.cern/doc/master/rootio.html

If it's not in there I will add it there; let me know where you want it.

Copy link
Member

@pcanal pcanal Jan 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a bit obscure, especially when 'just' reading the source from vi. It probably should be clarified that the information is available/recorded(?) in ./io/doc/TFile and in particular tfile.md and tdirectory.md
( as a side note the 'format' in those file, both in the text version and the render version seems (to me) much harder to read than the one here (probably the missing/removed column delimiter)

Copy link
Member Author

@Axel-Naumann Axel-Naumann Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

as a side note the 'format' in those file, both in the text version and the render version seems (to me) much harder to read than the one here (probably the missing/removed column delimiter

Fine, but that shouldn't block this PR.

That's a bit obscure, especially when 'just' reading the source from vi.

Are you complaining about doxygen syntax being obscure, or you not knowing what's in these files? (Serious question.) Either way, my mission is to deconfuse users not necessarily Philippe, and this PR seems to be a step in the right direction ;-) There are several parts missing, e.g. TFile::Open instead of constructor etc - but that info wasn't there to begin with. So - what do we do?

Copy link
Member

@pcanal pcanal Jan 25, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fine, but that shouldn't block this PR.

In my opinion it was essential. This documentation is not just for me but also essential for future maintainer and for external implementer of the format. It could not be removed if there was not a (readable) alternative available. Glad-fully that was resolved in a separate PR.

Are you complaining about doxygen syntax being obscure, or you not knowing what's in these files? (Serious question.)

I am just stating that (possibly due to my missing in-brain doxygen parser) given those strings, I can not find the text file that contains the information. So maybe we can add outside the view of doxygen the actual name of the file or directory that contains the information (to help with browsing the code through a text editor) [As this information is "essential" to the implementation/documentation of the code, one would expect it to be close to the code ... or at least easy to reach.]

Copy link
Collaborator

@ferdymercury ferdymercury May 12, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related to my last comment: doxygen/doxygen#9331

Copy link
Member

@pcanal pcanal May 18, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When do they tag a release with that feature?

Copy link
Collaborator

@ferdymercury ferdymercury May 18, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The ROOT online-docs are created with a self-built version of doxygen. If I remember correctly, @couet has compiled doxygen versions from git-master that were not exactly at a specific doxygen release, so maybe he can just 'git pull' and recompile on the build machine.
The next stable release will be 1.9.5 probably in four or five months I guess.

Copy link
Member

@couet couet May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes I tested 1.9.5 on my machine first before updating the one on the build machine.
It seems stable I will soon update the build machine.
And yes, we are using the most recent version of doxygen.

Copy link
Member

@couet couet May 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done:

sftnight@root-ubuntu-2004-3:~/doxygen/build$ doxygen --version
1.9.5 (fdd8e8e750e1b8e58b4d9cc758293f532278dcca)

be 8 instead of 4 bytes:

Byte Range | Member Name | Description
----------------|-----------|--------------
1->4 | Nbytes | Length of compressed object (in bytes)
5->6 | Version | TKey version identifier
7->10 | ObjLen | Length of uncompressed object
11->14 | Datime | Date and time when object was written to file
15->16 | KeyLen | Length of the key structure (in bytes)
17->18 | Cycle | Cycle of key
19->22 [19->26] | SeekKey | Pointer to record itself (consistency check)
23->26 [27->34] | SeekPdir | Pointer to directory header
27->27 [35->35] | lname | Number of bytes in the class name
28->.. [36->..] | ClassName | Object Class Name
..->.. | lname | Number of bytes in the object name
..->.. | Name | lName bytes with the name of the object
..->.. | lTitle | Number of bytes in the object title
..->.. | Title | Title of the object
-----> | DATA | Data bytes associated to the object

The first data record starts at byte fBEGIN (currently set to kBEGIN).
Bytes 1->kBEGIN contain the file description, when fVersion >= 1000000
it is a large file (> 2 GB) and the offsets will be 8 bytes long and
fUnits will be set to 8:
Byte Range | Record Name | Description
----------------|-------------|------------
1->4 | "root" | Root file identifier
5->8 | fVersion | File format version
9->12 | fBEGIN | Pointer to first data record
13->16 [13->20] | fEND | Pointer to first free word at the EOF
17->20 [21->28] | fSeekFree | Pointer to FREE data record
21->24 [29->32] | fNbytesFree | Number of bytes in FREE data record
25->28 [33->36] | nfree | Number of free data records
29->32 [37->40] | fNbytesName | Number of bytes in TNamed at creation time
33->33 [41->41] | fUnits | Number of bytes for file pointers
34->37 [42->45] | fCompress | Compression level and algorithm
38->41 [46->53] | fSeekInfo | Pointer to TStreamerInfo record
42->45 [54->57] | fNbytesInfo | Number of bytes in TStreamerInfo record
46->63 [58->75] | fUUID | Universal Unique ID

Begin_Macro
../../../tutorials/io/file.C
End_Macro
The structure of a directory is shown in TDirectoryFile::TDirectoryFile
A ROOT file is a file-system file storing objects, possibly inside directories.
Copy link
Contributor

@eguiraud eguiraud Jan 19, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A ROOT file is a file-system file storing objects, possibly inside directories.
A ROOT file stores objects in a file-system-like logical structure, possibly including directory hierarchies.

Copy link
Member Author

@Axel-Naumann Axel-Naumann Jan 19, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it's a file-system file, really :-) Happy to see other wording suggestions that preserve the meaning :-)

Copy link
Contributor

@eguiraud eguiraud Jan 20, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Better?

Copy link
Member Author

@Axel-Naumann Axel-Naumann Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to clarify the important point that a TFile will end up on your disk, as a regular file. I don't think your current wording gets that across: it talks about the content of a TFile.

Copy link
Contributor

@eguiraud eguiraud Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ooooh "a file-system file" means "it's a file in your file system", not "it's a file the content of which logically works like a file system"?

"An on-disk file" then?

Copy link
Member Author

@Axel-Naumann Axel-Naumann Jan 27, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds great!

TFile's base class' TDirectoryFile shows the structure of the TFile content.

\sa \ref IO
\sa \ref rootio
*/

#include <ROOT/RConfig.hxx>
Expand Down