Eliminate extra docstrings for FunctionField

[glwagner]

Because the extra docstrings cause confusion, here we want to recommend just one way of building FunctionField. See #2515

[loganpknudsen]

I think this will help with clarity when trying to use this function!

[navidcy]

I don't see where the confusion comes when there are docstrings for each method. Could you elaborate?

[glwagner]

Here's the docstring before this PR

help?> Oceananigans.Fields.FunctionField
  FunctionField{LX, LY, LZ}(func, grid; clock=nothing, parameters=nothing) where {LX, LY, LZ}

  Returns a FunctionField on grid and at location LX, LY, LZ.

  If clock is not specified, then func must be a function with signature func(x, y, z). If clock is specified, func must be a
  function with signature func(x, y, z, t), where t is internally determined from clock.time.

  A FunctionField will return the result of func(x, y, z [, t]) at LX, LY, LZ on grid when indexed at i, j, k.

  ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

  FunctionField{LX, LY, LZ}(func::FunctionField, grid; clock) where {LX, LY, LZ}

  Adds clock to an existing FunctionField and relocates it to (LX, LY, LZ) on grid.

  ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

  FunctionField(L::Tuple, func, grid)

  Returns a stationary FunctionField on grid and at location L = (LX, LY, LZ), where func is callable with signature func(x, y, z).

Three docstrings come up. But we only want users to use one of them. Moreover the second one is actually redundant with the first and provides no new information. The last one is supposed to be for internal use only. But as a user who is new to julia (perhaps), you may see only the last docstring. This is what happened over on the discussion linked at the top.

[navidcy]

OK fair. The statement wasn't generic -- it was only for this case :)

Is there a value to convert the docstrings for the methods we don't intend to be for users to comments so that developers know what the intention was there?

[navidcy]

Perhaps for the methods we don't intend to be for users we can consider converting the docstrings to comments so that developers know what the intention was?

I'll leave that up to you. LGTM!

[glwagner]

OK fair. The statement wasn't generic -- it was only for this case :)

Is there a value to convert the docstrings for the methods we don't intend to be for users to comments so that developers know what the intention was there?

That's what I did for one of them. For the other one the second function is not actually different from the first so I don't think there's much value.

[navidcy]

I had missed that green line addition for the comment! Nice!

[glwagner]

OK fair. The statement wasn't generic -- it was only for this case :)

Right and we should note this is also an issue for some other stuff; we have too many docstrings and it is probably confusing / not helpful

[navidcy]

It's less confusing than not having any docstrings, which was my experience with some other state-of-the-art ocean models out there (no need to name names).

[glwagner]

It's less confusing than not having any docstrings, which was my experience with some other state-of-the-art ocean models out there (no need to name names).

That's a rather low bar!