[cdt-dev] Using doxygen comments to filter undesired code completion ent

["Ploett Norbert" <norbert.ploett@xxxxxxxxxxx>]

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

Thomas Fletcher wrote:

> The other alternative is for us to be able to tack an attribute
> on as meta data to the completion information and allow the user
> to selectively filter that out.  You see this in the JDT where 
> there is a preference to not include methods which have @deprecated 
> Javadoc comments.  In the future we would like to do something
> similar (ie Doxygen and dynamic hover/help content), which means 
> that this whould also be exposed to content providers providing
> their help/completion information as plugins.

This sounds to me like the "big solution" but I like it and have looked
into it. Please comment whether I have the correct understanding and
whether this approach would be acceptable for the community. Ok, let's
go:

1.	CDT should be enabled to evaluate Doxygen docstrings for
purposes like code completion, hover help etc. This would not only help
sove my problem in the way describe below but I think that many could
benefit from the ability to use this widely recognized standard way of
documentation.

2.	Docstring information must be gathered by the source parsers and
included in the AST. So docstrings must be recognized as a part of the C
/ C++ syntax by the GNUCSourceParser resp. GNUCPPSourceParser.
Docstrings are an optional element before (or after?) any declaration.
So a docstring would become an optional part of all IASTDeclarations
objects.

3.	The docstring information is retrieved from objects implementing
IBinding (they acquire the information when created from the
corresponding AST element). IBinding has a method to read the docstring.

4.	These docstrings contain tagging information like a "deprecated"
tag or the "internal" tag Thomas Fletcher suggested. 

5.	The DOMCompletionContributor can now search the docstring
entries for tags like "deprecated" or "internal" and react accordingly 
- like filtering out a proposal if it is "deprecated" and the user's
preference is not to display deprecated entries, 
- or to omit them entirely if they are marked "internal" (this solves my
problem).

Beyond this the DOMCompletionContributor can of course use the docstring
to fill in the additional proposal info so that the documentation of the
function is displayed along with the code completion proposal entry.

So did I understand this correctly? The part I am most unsure about is
how much work would it be to extend the source parsers to incorporate
Doxygen docstrings. Comments welcome!


Norbert