Skip to content

Suggestions to improve documentation

I've been reading the km3io documentation to get started for the first time, and I feel there's some room for improvement. Here's my experience:

  • One of the first things mentioned in the introduction section is the existance of three classes (offline reader, online reade, and gSeaGen reader). I miss a link to a doxygen style document where I can see by myself what are the methods and members of each of these classes. Along the rest of the documentation examples are given of some of the methods (such as OfflineReader.header()..etc) and that's good, but I'd also like to inspect these classes and methods by myself, and this should be one of the the first things shown in the README (a few hours after starting to write this, I found out that the green button docs|latest brings to the sphinx page, and there one can click API Reference which leads to the documentation generated from the software. I would put this link in the README and explicitly say that this link shows the documentation generated from software).

  • At the end of the introduction the following example is given:

>>> import km3io
>>> from km3net_testdata import data_path
>>> f = km3io.OfflineReader(data_path("offline/numucc.root"))
>>> f[:4].tracks.dir_z

I see that the operator OfflineReader::[] is applied to an object of the OfflineReader class, and it returns some other object from a class with a member tracks, which in turn has a member dir_z. But there's no way to figure this out from the documentation generated from the software. From this example I would conculde that OfflineReader is just a list of objects. Another question that arises after reading this example is "Oh!, perhaps there's also an operator OfflineReader::<>, or an operator OfflineReader::][, or what not, that do other things?". The operator OfflineReader::[] does not appear in the documentation.

  • The section Offline files reader starts with the sentence In general an offline file has two methods to fetch data: the header and the events. The statement In general at the beginning of the sentence, suggests that this information is incomplete. What does it mean in general? What are the particular cases in which the offline files do not have two methods to fetch data? Coming again to the automatically generated documentation, (API Reference->km3io->submodules->km3io.offline), I don't see the method events documented there.

  • The example given in the Offline files reader section, shows the following:

>>> f
OfflineReader (10 events)
>>> f.keys()

How could a user know from the documentation (and not from the example) that typing f produces this output? Again, the question arises: is an offline reader just a vector/list of events? How should I know that? The code generated documentation says it's a class, and then shows a list of methods. But I don't see how I could conclude this behavior from the documentation. From the f.keys() method used in the example above, I would guess that there's and OfflineReader::keys() method but this method does not appear in the documentation for this class. I see the method OfflineReader::header::keys, but these two are not the same. I only figured this out by trying things myself, and not from the documentation.

  • At the end of the Offline Reader section, there's another example showing that f.events.tracks.E produces this output <Array [[117, 117, 0, 0, 0, ... 0, 0, 0, 0, 0]] type='10 * var * float64'>. This (as well as the rest of the membres from event and from tracks...etc) does not appear in the documentation generated by the software. And it is possibly the most important thing that users need to see in the documentation. How could I know about the OfflineReader::events::tracks::E method/member??? What other methods/members are there similar to this one?

To summarise, I think that the softare generated documentation still needs work.