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

[Smith, Barry F.]

> On Feb 6, 2019, at 2:01 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?

   Yeah, the above two examples are just wrong (probably inherited from before DM was a fully defined object). In both these cases they are collective on DA

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

   No page should just say collective.
> 
> 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>"?

   That would be fine. So there are two possibilities

       Collective on XXX 

    or 

       Logically Collective on XXX
> 
> 
> Thanks,
>   Dave
> 
>