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

[Aaron Puchert via Phabricator via cfe-commits]

aaronpuchert added a comment.

Thanks for working on this, I'd like to see this being fixed.



================
Comment at: clang/include/clang-c/Documentation.h:383
 CINDEX_LINKAGE
-CXString clang_ParamCommandComment_getParamName(CXComment Comment);
 
----------------
gribozavr2 wrote:
> 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.
I think @gribozavr2 is correct here, the chapter in the developer policy refers to the C API of LLVM, not Clang. The Clang documentation also says that libclang should be stable (http://clang.llvm.org/docs/Tooling.html#libclang).


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

https://reviews.llvm.org/D71966