Introduce clang_getCursorPrettyPrinted() for pretty printing
declarations. Expose also PrintingPolicy, so the user gets more
fine-grained control of the entities being printed.

The already existing clang_getCursorDisplayName() is pretty limited -
for example, it does not handle return types, parameter names or default
arguments for function declarations. Addressing these issues in
clang_getCursorDisplayName() would mean to duplicate existing code
(e.g. clang::DeclPrinter), so rather expose new API to access the
existing functionality.

I'm not too happy with the current version because of all the getters/setters/dispose functions. Has anyone a better idea? :) PrintingPolicy can be (mostly) mapped to an enum, but unfortunately PrintingPolicy::Indentation does not play well with that. Also, the enum probably wouldn't be too future proof, so I chose the opaque pointer approach.

The "See \c clang::PrintingPolicy for more information." references might be another issue. But this felt better than duplicating the already existing documentation...

Locally we've done something similar (adding a clang_getCursorPrettyPrintedDeclaration function, though without exposing the PrintingPolicy) and overhauled DeclPrinter to produce proper pretty names. This is a hack that works well for us, but can never be upstreamed since it breaks too much existing code (and some of the printing decisions are subjective). Your way is better.

I can point out differences in our implementations if you like. The diff is rather long, though.

Locally we've done something similar (adding a clang_getCursorPrettyPrintedDeclaration function, though without exposing the PrintingPolicy) and overhauled DeclPrinter to produce proper pretty names. This is a hack that works well for us, but can never be upstreamed since it breaks too much existing code (and some of the printing decisions are subjective). Your way is better.

You might consider to enhance PrintingPolicy for your use cases?

I can point out differences in our implementations if you like. The diff is rather long, though.

I've seen other C-API's (for Linear and Quadratic programming) follow a similar approach quite extensibly.

It would significantly reduce the size of the API.

You are right and rethinking this, I see no problem with it. I thought of that too (see my very first comment to this change), but then for some reason the PrintingPolicy::Indentation (unsigned : 8) has driven me to this version. I probably have only thought of strictly false/true values to set/get.

It might be worth adding some very simple get/set tests to ensure that properties are set as intended.

clang_PrintingPolicy_setProperty is already called in c-index-test.c and covered with test/Index/print-display-names.cpp. Do you have another kind of test in mind?

I'm not sure how to best test clang_PrintingPolicy_getProperty. I don't see how to get that cleanly covered within c-index-test.c, too. After calling the setter, one could call the getter and verify that it's the same. But c-index-test shouldn't do something like this. I've added a test in LibclangTest.cpp with which I'm not too happy (an extra parse just to test a getter feels wrong).

I think we have the basic functionality of the getter and setter covered. Testing each getter/setter for each property would mostly help to verify the mapping in the getters/setters - initially I've ruled out that possibility with the macros (once the macro is correct - but that's much easier to check). I would prefer to go back to the macro version than adding a test here that goes over all properties.