[Networkit] Documentation woes

Matteo Riondato matteo at cs.brown.edu
Fri Jul 14 23:51:18 CEST 2017


Hi all,

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. =)

Thanks,

Matteo

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Message signed with OpenPGP
URL: <http://lists.ira.uni-karlsruhe.de/pipermail/networkit/attachments/20170714/aa874fdb/attachment.sig>


More information about the NetworKit mailing list