Inconsistent Documentation

[lucidBrot]

I'm revisiting my notes from a lecture where we were using this library, and recall that some of us were confused by the documentation. I'm not entirely certain, but these are my observations:

• The text and example at this docs page refer to g.get_segments(). A function which does not seem to exist, as confirmed by a search in this repo

• This page in the docs clearly states for the existing function get_segment without a trailing s:

  The method get_segment returns 1 when the given node belongs to the partition of the source node (i.e., the minimum cut severs the terminal edge from the node to the sink), or 0 otherwise

  But then shows an example where the segment of the node 0 is said to be 1 and it is depicted on the picture as belonging to the sink, not the source. This is inconsistent.

• The underlying c code defines SOURCE = 0, SINK = 1. So I would assume that this is the correct way of assignment.

• There is a test using 0 as the source, underlining my belief.

• The documentation about the get_segment function itself does not state anything about this.

If you agree, it would make sense to clarify the documentation. :)

[pmneila]

Hi @lucidBrot,

Indeed, the documentation of the library is pretty outdated. I wrote it a long time ago and I haven't updated it very often as I think the library is rather simple to use and clear enough with the examples and docstrings.

However, regarding your comments:

• Indeed, there is no get_segments anymore. This function used to exist to retrieve the segments of all nodes, but was renamed to get_all_segments at some early stage of the code, and then removed and replaced by get_grid_segments.
• You are absolutely right with the other three comments. Numbers 0 and 1 are switched in the docs. I'm surprised nobody noticed that before.

I'll update the docs to fix the issues you found (and perhaps to fix some other minor issues). Thank you for letting me know.

[pmneila]

I just updated the docs. These issues should be solved now.

Thank you again for the suggestion!

[lucidBrot]

Thank you! That was a surprisingly fast response!