You can put whatever message you like when you deprecate the function, so perhaps here you could leave the old functions and say something like
PETSC_DEPRECATED_FUNCTION("Use X() and Y() (since version 3.13)") PetscErrorCode <https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode> OldFunction(); and you can leave the man page but change the "level" to "deprecated", which I don't think is usually done for simpler deprecations that are just name changes, that look like this: PETSC_DEPRECATED_FUNCTION("Use DMLocalToLocalBegin() (since version 3.5)") PETSC_STATIC_INLINE PetscErrorCode DMDALocalToLocalBegin(DM dm,Vec g,InsertMode mode,Vec l) {return DMLocalToLocalBegin(dm,g,mode,l);} (P.S. Once the web-based dev manual is merged, we could (easily, by editing an .rst file on the web) make a separate section on deprecation since right now it's buried in the style/usage guide, and doesn't have an example of deprecating macros: https://docs.petsc.org/en/psanan-docs-sphinx-dev-manual/developers/style.html#usage-of-petsc-functions-and-macros ) Am Mo., 23. März 2020 um 15:56 Uhr schrieb Satish Balay via petsc-dev < petsc-dev@mcs.anl.gov>: > On Mon, 23 Mar 2020, hzhang--- via petsc-dev wrote: > > > Lisandro: > > > > > * Please consider fixing MatProductCreate(A,B,C,&D) to take ownership > > > (that is, increase reference count) of the A,B, and the (optional) C > > > matrices provided as arguments. Otherwise it is way easy to get into > the > > > dangling pointer trap. > > > > > Can you give me a simple example of " get into the dangling pointer > trap"? > > We do not use reference count to keep track of A, B for Mat-Mat > operations > > in the current and previous versions. > > > > > > > > * A thing also missing in the new API is a way to "cleanup" the A,B,C > > > references, something MatProductReset(D) to get rid of (deallocates) > the > > > internal "product" context, thus removing from D the references to > A,B,C. > > > This would be useful if you just want to compute JUST the symbolic > product, > > > I'm using that in some code to compute the nonzero pattern of A^2. > > > > > Again, giving an example would help me understand. If you just want > > the symbolic product, you can call > > MatProductCreate() > > MatProductSetType() > > MatProductSetFromOptions() > > MatProductSymbolic(). > > This is equivalent to previous MatMatMultSymbolic(), and is used in some > > routines of PETSc. > > > > > > > > * It should be also considered to provide backward compatibility > > > PETSC_DEPRECATED calls to the previous MatMatMultSymbolic() > > > and MatMatMultNumeric(). It looks like it would be trivial to do, > though I > > > may be getting it wrong because I have not looked at all the details. > > > > > MatMatMultSymbolic/Numeric() are not recommended for users, and few > > developers ever used them. I only see one or two PETSc subroutines call > > them. I do not think we need provide backward compatibility > > PETSC_DEPRECATED calls for 6 pairs of such routines. > > If there is a simple map from old API to new API [just new names, or > reorder arguments] - we should include the old API with PETSC_DEPRECATED > > Alternative is PETSC_DEPRECATED with some error statement? Jed will know > better.. > > > Satish > > > > > Hong > > > >