On using is_one, is_subset, etc. versus isone, issubset, etc

[fingolfin]

Short version: We offer an alias is_one for Base.isone, and several similar ones. Questions:

1. should we set (and document) a rule which one to use in our code base (at least for new code)
2. should our methods and docstrings for isone be instead methods and docstrings for is_one?

Long version with more details:

We currently are setting up aliases for a bunch of Julia functions (from Base, LinearAlgebra, possibly more) for consistency with our new naming convention where we write is_FOO instead of isFOO. In particular, we have these (not necessarily complete):

# from AA
@alias is_one isone
@alias is_zero iszero
@alias is_symmetric issymmetric    # from LinearAlgbra; not done via @alias
@alias is_upper_triangular istriu  # from LinearAlgbra; not done via @alias

# from Nemo
@alias is_equal isequal
@alias is_finite isfinite
@alias is_inf isinf
@alias is_integer isinteger
@alias is_less isless
@alias is_real isreal

# from Hecke
@alias is_trivial istrivial      # from GroupsCore
@alias is_hermitian ishermitian  # from LinearAlgbra

# from Oscar
@alias is_subset issubset
@alias is_valid isvalid

For each of these aliases, we have set up a docstring:

help?> is_one
search: is_one is_nonzero is_connected is_nonnegative is_open_embedding is_non_zero_divisor is_pointed is_bounded

  is_one

  Alias for isone.

Now, there are some subtleties around this, and I think we need to make a few decisions and then enhance the naming convention documentation and possibly the code:

1. in each package, the aliases are set up at the very end. This is for the sake of the backwards compatibility aliases, which set up aliases like istrivial for is_trivial, and which thus must come after is_trivial is declared, so the safest place to do that is at the end. However, for the aliases going in the other direction, we really would want them as soon as possible, at least if we want subsequent code to use them.

   • I am trying to address this in this PR: Declare is_one, is_zero as early as possible Nemocas/AbstractAlgebra.jl#1178

2. inside the code of functions, should the OSCAR style guide suggest for new code...

   1. to always use isone (because it's the Julia way)
   2. to always use is_one (because it's the Oscar way)
   3. nothing (do whatever you like)

3. For method declaration with docstrings, things are bit more complex: if you write function is_one(...) with a docstring, then that docstring gets attached to is_one. Now suddenly, some of our isone/is_one methods are documented under one name, and some under the other name. Not good. In particular, the docstring which says is_one is an alias for isone may now be overlooked among the other docstrings. Some options for how to proceed:

   1. say in the style guide that it should be function isone (and the first line of the docstring should reference isone)
      • advantage: the output of ?is_one remains at a single entry, the user can see all docstrings at once via ?isone
      • drawback: goes against our simple naming rules (but to a degree we can't avoid that)
   2. say in the style guide that it should be function is_one (and again the first line of the docstring should reference is_one)
      • to me this option only makes sense if we change all methods at once in this fashion, else it'll be very confusing for the user

4. some thoughts related to the previous point

   • in the manuals, should we reference is_one or isone? (right now it is isone which is of course consistent with all our docstrings attached to isone, not is_one, so this goes hand in hand with the previous point
   • I've long argued that having 40 docstrings for isone all saying essentially the same is useless anyway. So perhaps we can reduce this to a handful, even a single one. I mention this because it kinda affects the previous point: if we had only a single docstring for it, we might as well attach it to is_one, or even to both...

[joschmitt]

Just because I already asked about this...
Regarding the two questions from the "short version":

1. Yes. I would prefer the is_* version for consistency, but in general I just want some documented decision, how code in Oscar should look like.
2. Yes, at least for the docstrings. I think it is hard to tell users, that for some methods they have to use (or look up) this convention and for others another. That's just the same problem as we already have with CyclotomicField vs. cyclotomic_field etc.

[JohnAAbbott]

In case this discussion is not yet closed...

1. I definitely second having a clearly documented decision/policy (possibly allowing a few exceptions -- being too rigid can be a bind)
2. Personally I find it harder to read lowercase names without underscores: e.g. ishermitian. Reading and understanding code can be hard work: I favour using easy-to-read names e.g. is_hermitian (or IsHermitian using CoCoA conventions -- I'm not proposing switching to CoCoA conventions!)
3. Regarding isone and is_one. It makes sense to use both: use isone when the intention is to call a native Julia function, and use is_one when the intention is to call an Oscar function.
4. Currently I have no good suggestion to resolve the doc-string problem. I have just tried ?isone, and it produced several screenfuls of doc. In contrast the entry for ?is_one is too succinct: basically no description, just "see isone".

Just for a laugh: with v 0.11.2 the doc for isone includes the following:

isone(x::arb)
  Return true if x is certainly not equal to oneo, otherwise return false.
  ──────────────────────────────
isone(x::acb)
  Return true if x is certainly zero, otherwise return false.

[fingolfin]

@JohnAAbbott sorry I missed your post here!

We have already settled on naming conventions in the developer docs. They seem to agree with what you wrote, I think :-).

Screenful of docs for isone is indeed still unresolved, "someone" should work on that.. if you are interested, let me know :-)

Regarding isone(x::arb) and isone(x::acb): ouch, good catch. I've submitted Nemocas/Nemo.jl#1407 to fix those. (Note that I am somewhat unhappy with those as I think they'll be easily mislead, as !isone does not anymore mean "is not one", just roughly speaking "can't prove it's one". Ah well)

[JohnAAbbott]

The Julia manual (PDF, page 208) make the following recommendation:

In general, only the most generic method should be documented, or even the function itself (i.e. the object
created without any methods by function bar end). Specific methods should only be documented if their
behaviour differs from the more generic ones.

Does Oscar have 3-way booleans? Might be useful for saying "definitely is 1", "definitely is not 1", or "don't know"