Problem/Motivation
I've read this 4 times and I don't get it:
* @param $graph
* A three dimensional associated array, with the first keys being the names
* of the vertices, these can be strings or numbers. The second key is
* 'edges' and the third one are again vertices, each such key representing
* an edge. Values of array elements are copied over.
*
* Example:
* @code
* $graph[1]['edges'][2] = 1;
* $graph[2]['edges'][3] = 1;
* $graph[2]['edges'][4] = 1;
* $graph[3]['edges'][4] = 1;
* @endcode
*
* On return you will also have:
* @code
* $graph[1]['paths'][2] = 1;
* $graph[1]['paths'][3] = 1;
* $graph[2]['reverse_paths'][1] = 1;
* $graph[3]['reverse_paths'][1] = 1;
* @endcode
* A three dimensional associated array, with the first keys being the names
* of the vertices, these can be strings or numbers.
This sentence isn't grammatical.
The second key is
* 'edges' and the third one are again vertices
I wasn't sure if this was a typo and it should be quoted as 'vertices', a literal string. But looking at the example, it's not.
each such key representing
* an edge.
Does that mean that each key of the 'edges' array is the name of a vertex, that is, matches a key in the main array?
> Values of array elements are copied over
I have no idea what that means.
Copied over -- does that mean copied from one place to another? In which case, from where to where? Or does it mean overwritten?
Is it trying to say that the values don't mean anything? They are all 1 in the example code, so I suspect that might be the case.
> * On return you will also have:
Return? This is a constructor. It doesn't return anything. What does this mean?
For a novice who is familiar with PHP, perhaps the first steps in making progress on this issue is to:
- Determine which file the documentation block in the issue description is from and add that info to the issue description.
- Figure out what the $graph parameter Is used for in order to improve the docblock.