[PATCH] D71966: [Wdocumentation][RFC] Improve identifier's of \param

[Dmitri Gribenko via Phabricator via cfe-commits]

gribozavr2 added a comment.

In D71966#1840957 <https://reviews.llvm.org/D71966#1840957>, @Mordante wrote:

> So if I understand correctly:
>
> - `getParamNameAsWritten` will become `getArgText`
> - The `getParamName` will do the translation from the name in the documentation to the name in the current function declaration. If the parameter index is invalid the function will fail (with an assertion error) and not fallback to call `getArgText`.


Yes, that would be my preference. Thanks!



================
Comment at: clang/include/clang-c/Documentation.h:383
 CINDEX_LINKAGE
-CXString clang_ParamCommandComment_getParamName(CXComment Comment);
 
----------------
Mordante wrote:
> gribozavr2 wrote:
> > Mordante wrote:
> > > gribozavr2 wrote:
> > > > Please don't modify existing APIs in libclang -- it provides a stable API and ABI, and what has shipped, can't be changed. New functionality has to be exposed as new functions, while old functions should be kept working to the extent possible. It means that the resulting API can be subpar, but oh well, a stable ABI is a contract of libclang.
> > > I thought I had read this API was allowed to change, but required adding information to the release notes. (I can't find it quickly.)
> > > I'll undo the changes to the existing functions and add new functions instead.
> > > I thought I had read this API was allowed to change
> > 
> > It would be interesting to find that doc. As far as I understand, libclang has a strict API & ABI stability rule.
> > 
> > > I'll undo the changes to the existing functions and add new functions instead.
> > 
> > Thanks!
> > 
> >> I thought I had read this API was allowed to change
> > It would be interesting to find that doc. As far as I understand, libclang has a strict API & ABI stability rule.
> My interpretation of http://llvm.org/docs/DeveloperPolicy.html#c-api-changes gave me this impression.
I see. Index.h explains the policy for libclang: https://github.com/llvm/llvm-project/blob/master/clang/include/clang-c/Index.h#L32-L33

If you feel like doing so, feel free to submit a patch for the developer policy to clarify libclang stability guarantees.


CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D71966/new/

https://reviews.llvm.org/D71966