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

[Matthew Knepley]

On Wed, Feb 6, 2019 at 3:03 PM Dave May via petsc-dev <petsc-dev at mcs.anl.gov>
wrote:

> * 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>"?
>

This has always bugged me. It should say, I think, 'Collective on <arg
name>", or "Logically collective on <arg name>".

  Thanks,

     Matt


> Thanks,
>   Dave
>
>
>

-- 
What most experimenters take for granted before they begin their
experiments is infinitely more interesting than any results to which their
experiments lead.
-- Norbert Wiener

https://www.cse.buffalo.edu/~knepley/ <http://www.cse.buffalo.edu/~knepley/>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190206/70c82ad6/attachment.html>