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

[Dave May]

On Thu, 7 Feb 2019 at 09:27, Hapla Vaclav <vaclav.hapla at erdw.ethz.ch> wrote:

>
>
> On 6 Feb 2019, at 21:08, Matthew Knepley via petsc-dev <
> petsc-dev at mcs.anl.gov> wrote:
>
> 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>".
>
>
> +1
>
> I also think it's a property of the concrete argument and not the class.
>

Completely agree.



> But it would be an epic task to rewrite it everywhere.
>

Well, we have to start somewhere.

Rather than a re-write I'd advocate adopting a better style in anything new
you write and cleaning up whenever you edit existing code.

In PR #1365 I've explicitly indicated which variable is assumed to be
logically collective.


>
> Vaclav
>
>
>   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/20190207/25005153/attachment.html>