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

[Smith, Barry F. via petsc-dev]

> On Feb 6, 2019, at 2:01 PM, Dave May via petsc-dev <petsc-dev@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
> 
>