Incorrect description in plot_plot3d.py

[bdlucas1]

The user facing description in plot_plot3d.py isn't quite right:

Plots with Points Having 3 Items.

"Items" is a bit vague but I can't think of an interpretation under which it is completely correct:

• ContourPlot of equations of the form f(x,y)==g(x,y) have 2 items
• If you consider each complex number to be 2 items then
  • ComplexPlot3D has 4 items (one input complex number, one output complex number displayed as magnitude and phase)
• If you consider each complex number to be single item then
  • ComplexPlot3D has 2 items
  • ComplexPlot has 1.5 items (one input complex number, one output scalar which is the phase of the output complex number)

I can't think of a good user-facing summary for that module. That module is useful from a code organization perspective (it groups classes that share the _Plot3D base class) but not from a user-facing documentation perspective. I think the underlying problem is that a single mechanism is used for both organizing code and for organizing the document structure. That is reasonable when docstrings are used to document the code itself, but maybe not so much when the docstrings are documenting something else.

[rocky]

The user facing description in plot_plot3d.py isn't quite right:

Plots with Points Having 3 Items.

"Items" is a bit vague

Yes, it is vague because it can mean several different things

but I can't think of an interpretation under which it is completely correct:

• ContourPlot of equations of the form f(x,y)==g(x,y) have 2 items

The thing about a contour plot is that the value forms the 3rd item.

• If you consider each complex number to be 2 items then

  • ComplexPlot3D has 4 items (one input complex number, one output complex number displayed as magnitude and phase)

Yep. So the description could be more than two items instead of three items.

• If you consider each complex number to be single item then

  • ComplexPlot3D has 2 items
  • ComplexPlot has 2.5 items (one input complex number, one output scalar which is the phase of the output complex number)

I can't think of a good user-facing summary for that module. That module is useful from a code organization perspective (it groups classes that share the _Plot3D base class) but not from a user-facing documentation perspective. I think the underlying problem is that a single mechanism is used for both organizing code and for organizing the document structure. That is reasonable when docstrings are used to document the code itself, but maybe not so much when the docstrings are documenting something else.

This is basically the system we inherited. It will probably eventually get fixed when we replace the homegrown documentation system.

On the one hand, I don't like adding more to a not-fully-thought-out documentation system. But on the other hand, user-facing documentation is important.

[bdlucas1]

The thing about a contour plot is that the value forms the 3rd item.

For ContourPlots of the form f(x,y) that is true. For ContourPlots of the form f(x,y)==g(x,y) it's not - there is no value manifest to the user, and all the user sees is lines, no shading as in the first form. (Internally it's implemented by evaluating f(x,y)-g(x,y) and taking the contour at 0, so the two forms share code, but that's an implementation detail and is hidden from the end user.)

[rocky]

The thing about a contour plot is that the value forms the 3rd item.

For ContourPlots of the form f(x,y) that is true. For ContourPlots of the form f(x,y)==g(x,y) it's not - there is no value manifest to the user,

Not true, the zero or one-ness is which becomes apparent as a line is the third (or more than second) item.

But at any rate, feel free to adjust as you see fit. We could also just punt and say this section is for X and Y and not try to justify why we put X and Y together. — we just do it.

[bdlucas1]

It will probably eventually get fixed when we replace the homegrown documentation system.

I think this is the correct fix, rather than trying to further torture the language of the description. In which case this issue would be placed in the "replace documentation system" epic if we had such a thing.