[Networkit] Documentation woes
matteo at cs.brown.edu
Fri Jul 14 23:51:18 CEST 2017
The C++ documentation for the SSSP class says that SSSP::getStack() “returns a stack of nodes ordered in decreasing distance from the source”.
Looking at the implementation of the BFS and Dijkstra algorithms in the homonymous classes (I haven’t looked at the Dyn* implementations), the truth seems to be that the nodes are actually ordered by *increasing* distance from the source. Experiments confirm this fact. This ordering makes a bit more sense due to the way the SSSP algorithms work (exploring from the source).
Which one is correct: the code or the docs?
Also, it’s a little surprising that the documentation for SSSP, BFS, Dijkstra, and many other classes is in the Graph module (https://networkit.iti.kit.edu/api/doxyhtml/group__graph.html) and not in the Distances module, especially considering that the implementations reside in the distance/ directory, not in the graph/ directory.
The DynBetweenness class is also documented in the Graph module but it should probably be documented in the Centrality module.
All these misclassifications are due to wrong “@inmodule” Doxy directive in the .h files of these classes.
KruskalMFS, RandomSpanningForest, and Sampling are documented in the Graph module and their implementations are in the graph/ directory, but I wonder whether that is the best place for them (in terms of both the location of the implementation and the location of the documentation).
As a side note, I had to debug my code for way too long before realizing that the cause of what I was seeing was that the NetworKit code and its docs didn’t match. Documentation that doesn’t match the code is worse than no documentation. =)
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 801 bytes
Desc: Message signed with OpenPGP
More information about the NetworKit