Improve docstrings for Cones (and possibly others)

[MicahGale]

This pertains to the Cone docstrings: https://docs.openmc.org/en/stable/pythonapi/generated/openmc.Cone.html, and others.

The documentation for openmc.Cone lacks a quadric surface equation, and more importantly, an intuitive explanation of r2. [X|Y|Z]Cone does include the equation, but r2 is still not super intuitive.

In general many surfaces' documentation probably needs more intuitive explanations.

Thanks @pshriwise for making me find this.

[MicahGale]

I can do this. I just can't assign myself.

[MicahGale]

Other thought. Example figures from @gridley's work (i.e., 3D renders) might be helpful.

[MicahGale]

It was discovered that r2 is r^2 and not r_2, which isn't very intuitive. How bad would a refactor break things? I'm thinking either: r, r_squared, or r_sq. To prevent breaking things we could keep r2 as a backup kwarg.

I think also the fact that this is a double cone needs to be clearer.

Third thought: an angle is a lot more intuitive. So I think a constructor that takes theta would be good. I'm thinking either:

1. adding a theta kw-arg to __init__
2. Or adding a @staticmethod that is essentially a factory.

What's the most openMC-ic way?

[gridley]

"Parameter related to the aperture" Lol what. That isn't the best! Is this the radius squared one unit along the cone's axis? I agree it'd be good to include a sketch. A 3D rendering would be nice, but perhaps convey only marginally more info!

[MicahGale]

"Parameter related to the aperture" Lol what. That isn't the best! Is this the radius squared one unit along the cone's axis?

We found out that it is the square of the radius 1 unit along the axis. The square of the slope of the edge works quite nicely.

A 3D rendering would be nice, but perhaps convey only marginally more info!

Touche. Time to either get good at inkscape (@tjlaboss) or scour wikimedia.

[pshriwise]

Thanks for taking this on, @MicahGale! Let's get the documentation updated for now and revisit the parameter naming.

Mention of the XConeOneSided and similar composite surfaces here is probably appropriate

[MicahGale]

Good idea. Best not to make this monolithic. Should I open a separate issue to discuss the possible refactor?