On Thu, 7 Feb 2019 at 09:27, Hapla Vaclav <vaclav.ha...@erdw.ethz.ch> wrote:
> > > On 6 Feb 2019, at 21:08, Matthew Knepley via petsc-dev < > petsc-dev@mcs.anl.gov> wrote: > > On Wed, Feb 6, 2019 at 3:03 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? >> 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/> > > >
