[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
AW: [cdt-dev] Using doxygen comments to filter undesired code completion entries
|
Hello Alain and all,
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?
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?
Thank you,
Norbert Ploett
-----Ursprüngliche Nachricht-----
Von: cdt-dev-bounces@xxxxxxxxxxx [mailto:cdt-dev-bounces@xxxxxxxxxxx] Im Auftrag von Alain Magloire
Gesendet: Montag, 8. August 2005 18:45
An: CDT General developers list.
Betreff: RE: [cdt-dev] Using doxygen comments to filter undesired code completion entries
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
_______________________________________________
cdt-dev mailing list
cdt-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/cdt-dev
