RE: [cdt-dev] Using doxygen comments to filter undesired code com pletio

[Alain Magloire <alain@xxxxxxx>]

> Behalf Of Ploett Norbert
> Subject: AW: [cdt-dev] Using doxygen comments to filter undesired code
> completion entries
> 
> Hello Alain and all,
>

Bonjour,

	I read your _sad story_ in PR 104792.

(For more detailed context please refer to
https://bugs.eclipse.org/bugs/show_bug.cgi?id=104792)

It brought tears to my eyes.  In a way it shows the Clear Range And
Practicality (C.R.A.P.!) of the C/C++ language.

> ok, I understand that doxygen cannot be considered a universal standard,
> still a pluggable comment parser would be appreciated.
> 
> Now there is another problem I found: I did a proof-of-concept
> implementation of a comment processor which made the
> DOMCompletionContributor suppress such CCompletionProposals which referred
> to an identifier which hat a @@deprecated comment on the same line of
> code. It did not help me because I found that the same entries were also
> found by the SearchCompletionContributor.
> 
> So it seems that filtering of proposals on the base of source code
> annotations can be done only if all completion contributors follow a
> uniform policy for suppressing proposals.
> 
> Which becomes even more difficult when we consider that new completion
> contributors can be added via the
> org.eclipse.cdt.ui.completionContributors extension point! Is my reasoning
> correct so far?
> 

Yes.

> One way to reach such a uniform policy could be to augment
> ICCompletionProposal with methods to get annotation values which should be
> filled in by the completion contributors if available. The filtering
> strategy could then be implemented in the completion processor.
> 
> I looked a little further and saw more problems: Assuming a comment
> processor were to store docstrings in the corresponding AST nodes. The
> DOMCompletionContributor scans the AST and processes the results in the
> form of an IBinding[] to create the proposals, the IBindings do not
> currently support transporting annotations. The
> SearchCompletionContributor retrieves an IMatch[] from it's query, and
> IMatch does not have the capabilities for transporting annotations either.
> So we have already two interfaces, IBinding  and IMatch  to extend - I
> have no idea about the consequences / side effects of this.
> 
> Can you give me feedback whether a solution like this is inevitable or
> whether maybe there is a more elegant way to do this?
>

First, let's try to disentangle things;
(1) Having support for doxygen
	(i) doxygen could be a contributor to the Help, contributing
hovering docs.
(2) Making the comment parsing generic, so other works like a ToDo plugin
could re-use it or other Cdoc style comments could be done easily.

Your PR brought some flaws to the contributing scheme:
- how to disable unwanted contributors
- how to set policies for contributors.

So far the only policy we have for completions (code assist) is in the
preference page:
Preferences --> C/C++ --> Editor --> Code Assist

JDT give us a somewhat bias example, since JavaDoc tags are part of the
language, not the case for C/C++.  It is unclear on how to deal with
policies coming for different contributions influencing other contributors.

But it would be nice to get (1) (2) going and as we learn about this, an
elegant solution may present itself.  Using the ASTNode and IBinding class
hierarchy to describe the doxygen tags looks interesting, if it is
implemented separately from the DOM parser.  At this point, I do not think
we want to force the parser to accumulate and parse comments.