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

[Alain Magloire <alain@xxxxxxx>]

Doug wrote:
> 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.


Yes, sharing the same feeling, taxing the parser to do some preprocessor
work could be prohibitive.

On the side note, I'm working on/off on a TODO contribution plugin for the
CDT, it is loosely base on the code by Victor M. The TODO plugin share some
similarities to the doxygen.

> -----Original Message-----
> From: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx] On
> Behalf Of kesselhaus@xxxxxxx
> Sent: Friday, August 05, 2005 12:28 PM
> To: CDT General developers list.
> Subject: Re: [cdt-dev] Using doxygen comments to filter undesired code
> completion entries
> 
> 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 +++
> _______________________________________________
> cdt-dev mailing list
> cdt-dev@xxxxxxxxxxx
> https://dev.eclipse.org/mailman/listinfo/cdt-dev