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

[Doug Schaefer <dschaefer@xxxxxxxxxx>]

I agree. I think the main reason, other than finding someone to work on 
such things, that we haven't looked at this is because we're not sure 
doxygen is as standard as javadoc. The best solution would be to allow 
the user to select from a number of alternative comment parsers that 
people could provide. And, obviously, the best way to do that is through 
an extension point and making sure we provide enough flexibility for 
different comment parsers to be written.

Something worth considering.

Doug

kesselhaus@xxxxxxx wrote:

> 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
> >
> >    
>
>  


--
Doug Schaefer, Senior Software Developer
IBM Rational Software, Ottawa Lab
Kanata, Ontario, Canada