Document that Either should not be used in new code #1699
Conversation
mdickinson
added
component: documentation
| @@ -238,10 +238,11 @@ Traits | |||
| .. autoclass:: ToolbarButton | |||
| :show-inheritance: | |||
|
|
|||
| .. autoclass:: Either | |||
| .. autoclass:: Union | |||
There was a problem hiding this comment.
Deliberately swapping the order so that Union appears before Either in the docs.
There's also a drive-by fix here: :show-inheritance: was missing for Union, for no reason that I can discern.
| @@ -269,7 +269,7 @@ the table. | |||
| .. index:: PythonValue(), Range(), ReadOnly(), Regex() | |||
| .. index:: Set() String(), This, Time() | |||
| .. index:: ToolbarButton(), true, Tuple(), Type() | |||
| .. index:: undefined, UUID(), ValidatedTuple(), WeakRef() | |||
| .. index:: undefined, Union(), UUID(), ValidatedTuple(), WeakRef() | |||
There was a problem hiding this comment.
Another drive-by fix: Union was missing from this list of index entries.
| @@ -408,7 +408,7 @@ the table. | |||
| | Union | Union( *val1*\ [, *val2*, ..., *valN*, | | |||
| | | \*\*\ *metadata*] ) | | |||
| +------------------+----------------------------------------------------------+ | |||
| | UUID [4]_ | UUID( [\*\*\ *metadata*] ) | | |||
| | UUID | UUID( [\*\*\ *metadata*] ) | | |||
There was a problem hiding this comment.
Dropped the [4] footnote, which talked about Python 2.5; I've re-used it for Either.
There was a problem hiding this comment.
Nitpick: footnote 4 comes before footnote 3 (attached to Function and Method) in the text.
There was a problem hiding this comment.
Thanks; fixed. At the same time, I fixed that the current footnotes start from the third natural number, rather than the second as is more conventional.
| @@ -408,7 +408,7 @@ the table. | |||
| | Union | Union( *val1*\ [, *val2*, ..., *valN*, | | |||
| | | \*\*\ *metadata*] ) | | |||
| +------------------+----------------------------------------------------------+ | |||
| | UUID [4]_ | UUID( [\*\*\ *metadata*] ) | | |||
| | UUID | UUID( [\*\*\ *metadata*] ) | | |||
There was a problem hiding this comment.
Nitpick: footnote 4 comes before footnote 3 (attached to Function and Method) in the text.
This PR adds notes to the user manual and API documentation to discourage users from using Either in new code. (Union should be preferred.) (cherry picked from commit c5cfdde)
mdickinson
removed
the
porting: needs backport to 6.4
This PR adds notes to the user manual and API documentation to discourage users from using
Eitherin new code. (Unionshould be preferred.)Closes #1610