<div dir="ltr">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<div><br></div><div><pre style="overflow:auto hidden;font-family:Consolas,"Deja Vu Sans Mono","Bitstream Vera Sans Mono",monospace;font-size:0.95em;letter-spacing:0.015em;line-height:15.96px;padding:0.5em;border:1px solid rgb(204,204,204);background-color:rgb(248,248,248);color:rgb(0,0,0)"><span class="gmail-n">PETSC_DEPRECATED_FUNCTION</span><span class="gmail-p">(</span><span class="gmail-s" style="color:rgb(64,112,160)">"Use X() and Y() (since version 3.13)"</span><span class="gmail-p">)</span> <span class="gmail-n"><a href="https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode" style="color:inherit">PetscErrorCode</a></span> <span class="gmail-n">OldFunction</span><span class="gmail-p">();</span>
</pre><div><br></div><div>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:<br></div></div><div><br></div><div>    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);}<br></div><div><br></div><div>(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: <a href="https://docs.petsc.org/en/psanan-docs-sphinx-dev-manual/developers/style.html#usage-of-petsc-functions-and-macros">https://docs.petsc.org/en/psanan-docs-sphinx-dev-manual/developers/style.html#usage-of-petsc-functions-and-macros</a>)</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Am Mo., 23. März 2020 um 15:56 Uhr schrieb Satish Balay via petsc-dev <<a href="mailto:petsc-dev@mcs.anl.gov">petsc-dev@mcs.anl.gov</a>>:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On Mon, 23 Mar 2020, hzhang--- via petsc-dev wrote:<br>
<br>
> Lisandro:<br>
> <br>
> > * Please consider fixing MatProductCreate(A,B,C,&D) to take ownership<br>
> > (that is, increase reference count) of the A,B, and the (optional) C<br>
> > matrices provided as arguments. Otherwise it is way easy to get into the<br>
> > dangling pointer trap.<br>
> ><br>
> Can you give me a simple example of " get into the dangling pointer trap"?<br>
> We do not use reference count to keep track of A, B for Mat-Mat operations<br>
> in the current and previous versions.<br>
> <br>
> ><br>
> > * A thing also missing in the new API is a way to "cleanup" the A,B,C<br>
> > references, something MatProductReset(D) to get rid of (deallocates) the<br>
> > internal "product" context, thus removing  from D the references to A,B,C.<br>
> > This would be useful if you just want to compute JUST the symbolic product,<br>
> > I'm using that in some code to compute the nonzero pattern of A^2.<br>
> ><br>
> Again, giving an example would help me understand. If you just want<br>
> the  symbolic product, you can call<br>
> MatProductCreate()<br>
> MatProductSetType()<br>
> MatProductSetFromOptions()<br>
> MatProductSymbolic().<br>
> This is equivalent to previous MatMatMultSymbolic(), and is used in some<br>
> routines of PETSc.<br>
> <br>
> ><br>
> > * It should be also considered to provide backward compatibility<br>
> > PETSC_DEPRECATED calls to the previous MatMatMultSymbolic()<br>
> > and MatMatMultNumeric(). It looks like it would be trivial to do, though I<br>
> > may be getting it wrong because I have not looked at all the details.<br>
> ><br>
>  MatMatMultSymbolic/Numeric() are not recommended for users, and few<br>
> developers ever used them.  I only see one or two PETSc subroutines call<br>
> them. I do not think we need provide backward compatibility<br>
> PETSC_DEPRECATED calls for 6 pairs of such routines.<br>
<br>
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<br>
<br>
Alternative is PETSC_DEPRECATED with some error statement? Jed will know better..<br>
<br>
<br>
Satish<br>
<br>
> <br>
> Hong<br>
> <br>
<br>
</blockquote></div>