[petsc-dev] Man pages usage of "Collective on XXX"

[Dave May]

* I notice that most man pages will say
  Collective on <type>
e.g.
https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMDA/DMDACreate.html

* Some others say
  Collective on <implementation-name>

e.g.
https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DMDA/DMDACreateNaturalVector.html

or

https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/DM/DMCompositeAddDM.html

In the former, at least the word "DMDA" gets linked back to the
implementation, whilst in the latter "DMComposite" does not.

Should "Collective on <implementation-name>" be avoided?
It is potentially somewhat unclear given that the name of the
implementation does not appear anywhere in the arg  list (type or variable
name).

That said, "collective on <type>" could be similarly criticized if a method
existed with two args of the same type.

* Many of the methods in this file

  www.mcs.anl.gov/petsc/petsc-current/src/dm/impls/shell/dmshell.c.html

simply say "Collective" (without a type or implementation name), or they
say "Logically Collective on XXX"

I do realize that there is a pattern that the statement "collective on xxx"
or "not collective" applies (implicitly) to the first argument of any PETSc
function call (at least that I've come across) so possibly just indicating
the method as "Collective" might suffice (assuming (i) there is a pattern
and (ii) everyone knows about the pattern).

Q: Should I make a PR to unify these man pages (and any others I spot) to
just say "Collective on <type>"?


Thanks,
  Dave
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190206/a5462462/attachment.html>