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

[kesselhaus@xxxxxxx]

I'm having a bad feeling on concentrating only on doxygen like comments,
even though, I'd prefer doxygen personally. E.g. at work, we do not use
doxygen like comments, even though, they are structured in some kind.
The question in fact is, if we ever get rid of the kind of comments provided
by templates and step over to doxygen, but the company is a rather big one.

I think a comment parser should be there, but not specifically in the
GNUCSourceParser. Also, Doxygen comments can be anywhere in your code.
ex.:
--------
void myfunc1() {}
void myfunc2() {}
void myfunc3() {}

int a; /*!< Var a */
int b;

/*! \fn void myfunc1()
 *  \brief myfunc1 blah blub 
 *
 *  \fn void myfunc2()
 *
 *  \fn void myfunc3()
 *
 */

/*! \var b
 *  \brief whatever b is useful for
 */
---------

Though, best would be an comment parser, but decoupled from the source
parsers. The info has to be comebined by other meanings.
Also I could think of something like regex-kind or template based, in order
to be more generic. Doxygen parser could be an implementation of such
generic behaviour. The comment parsers should then provide the info or maybe
add them to the AST.

Just my 0.02€.



> --- Ursprüngliche Nachricht ---
> Von: "Ploett Norbert" <norbert.ploett@xxxxxxxxxxx>
> An: "CDT General developers list." <cdt-dev@xxxxxxxxxxx>
> Betreff: [cdt-dev] Using doxygen comments to filter undesired
> code	completion entries
> Datum: Fri, 5 Aug 2005 12:04:06 +0200
> 
> (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
> _______________________________________________
> cdt-dev mailing list
> cdt-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/cdt-dev
> 

-- 
5 GB Mailbox, 50 FreeSMS http://www.gmx.net/de/go/promail
+++ GMX - die erste Adresse für Mail, Message, More +++