Fix degree(::Graph) documentation

[YueRen]

Addresses #4440

[YueRen]

Could somebody from the polymake team please check whether the changes are okay? If not, feel free to push changes to the branch. Many thanks in advance!

[lgoettgens]

The docstring states If the graph is directed, the neighbors reachable via outgoing edges are returned., so the current behaviour of neighbors is as documented.

Maybe @benlorenz or @lkastner have some opinion on this?

[lgoettgens]

Sorry for the confusion. My comment was about the function neighbors that you modified. This functions states If the graph is directed, the neighbors reachable via outgoing edges are returned. in its docstring and may thus not be changed in this way.
This would then just mean that you would need to find a different way to patch degree

[YueRen]

Okay, I think I got confused. The neighbors docstring clearly states that only out-neighbors are counted, however the degree docstring (which is how I stumbled upon this issue) does not.

Should we
(a) change the neighbors function so it counts both out- and in-neighbours as in the pull-request (+ update the documentation accordingly)
(b) change the degree function so it counts both out- and in-neighbours
(c) update the degree documentation so it warns the use that only out-neighbours are counted.

[benlorenz]

The docstring for neighbors (which you are modifying here) does have this. Unfortunately it is not mentioned for degree.

The neighbors function does match what julia Graphs.jl does: https://juliagraphs.org/Graphs.jl/v1.5/core/#Graphs.neighbors-Tuple{AbstractGraph,%20Integer} (defaulting to outneighbors)
But we chose degree to be consistent with neighbors, while Graphs.jl counts all edges in that case.

In any case these are decisions that were made and it is not a clear bugfix. So we cannot change that behavior until 2.0.
I would suggest adding a note to the documentation of degree.
In hindsight it would have been better to disallow these for directed graphs to avoid confusion.

Edit: We do also have all_neighbors, not sure how one would call a corresponding function for degree though.

[YueRen]

Okay, I've changed the commit. It now only adds a comment to the docu of degree.

offending changes removed

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.36%. Comparing base (43499a7) to head (658ea33).
Report is 64 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4441      +/-   ##
==========================================
- Coverage   84.39%   84.36%   -0.04%     
==========================================
  Files         663      663              
  Lines       87938    87938              
==========================================
- Hits        74214    74187      -27     
- Misses      13724    13751      +27     

Files with missing lines	Coverage Δ
src/Combinatorics/Graphs/functions.jl	96.72% <ø> (ø)

... and 2 files with indirect coverage changes