Document the forceRebuild extension

[HighCommander4]

No description provided.

[HighCommander4]

@kadircet @hokein I don't have the permission to add you as reviewer in this repo, but could you take a look please?

[kadircet]

Thanks for the patch, I feel like this isn't a "useful" extension nowadays as we've improved both picking up compile flags dynamically and also are keeping better track of preamble valid-ness.

Any specific motivation for the patch, apart from increasing docs coverage?

@sam-mccall were there any other historical use cases for this extension that might still be relevant? maybe we can just retire it going forward in clangd.

[HighCommander4]

Any specific motivation for the patch, apart from increasing docs coverage?

I believe this is being used by clangd users at Ericsson, with a modified vscode client.

The use case is a client-side action that creates a header file for which an #include was present (and unresolved due to the file not yet existing) in an open source file. Sending a forceRebuild causes clangd to re-check for the existence of the newly created file and remove the diagnostic.

Please do not remove the feature :)

[kadircet]

The use case is a client-side action that creates a header file for which an #include was present (and unresolved due to the file not yet existing) in an open source file. Sending a forceRebuild causes clangd to re-check for the existence of the newly created file and remove the diagnostic.

Ok but I think that's exactly the improvement I mentioned above. If they were to send a didChange, even without forceRebuild set, clangd should still rebuild that preamble nowadays.

[HighCommander4]

If they were to send a didChange, even without forceRebuild set, clangd should still rebuild that preamble nowadays.

Oh, interesting!

Let me follow up on this; will change the PR to draft for now.

[kadircet]

argh, now i see why the confusion in the main thread occured. I wrote this comment but forgot to hit submit :( still getting used to the PR workflow..

[kadircet]

well that isn't strictly true nowadays, we actually do track missing include directives when building a preamble and will invalidate the preamble if any of them become available.

the only scenario that I can think of for forceBuild to be useful nowadays is, when foo.h becomes available in an earlier include search path than it was found before.