Community
Participate
Working Groups
Doxygen is the de-facto standard for C/C++ documentation generation, there should be a "generate element comment" command sensible to the user selection (function prototype, class, define, etc). KDevelop (for C and C++ with Doxygen) and JDT (for Java with JavaDoc) already have this feature.
Help wanted. No one is currently looking at this.
hi, We have an internal plug-in for this that I'm looking to clean up and submit for CDT 5.0 if possible. I spoke with Anton at the fall summit about some potential architectural issues involved which I'd like to ask advice on in a bit more detail: The overall idea is pretty simple - allow people to plug-in different SourceViewer tools (e.g. scanners, auto-edit-strategies etc..) for 'documentation comments'. Documentation comments would be those singleline or multiline comments which are determined by the plug-in to be processable by the tool in question. There is a complication if you try to allow multiple plug-ins to be active at the same time - e.g. allow projectA to be associated with doxygen, and allow projectB to be associated with cppdoc. The two approaches to resolving this I've looked at each have their own problems. === Approach 1: Retain the current ICPartition types, and have the plug-in's examine the multi-line or single-line partitions when they are invoked in order to alter their behaviour as appropriate. This works fine but is working around some of the editor architecture. === Approach 2 as suggested by Anton: Define two new partition types for doc_multiline and doc_singleline and allow plug-ins to hook into FastCPartitionScanner to intercept any singleline or multiline partitions. The issue here is we need to change the partitioner based on the associated documentation tool, and that the mechanism for doing this (IDocumentSetupParticipant) does not provide the path to the document being setup, I guess that as in general it may not have one. For documents that are in the workspace, the relative path would enable configuring the fast partitioner to recognize different documentation comments depending on the documentation tool associated with the containing project. I've experimented with introducing updatable state to the FastCPartitionScanner, and configuring it at CEditor.doSetInput time. This does the trick but I've not yet understood if this is legitimate with respect to other document clients. If not I'd intend to look at writing an IDocumentSetupParticipantExtension that document setup participants could optionally implement to recieve this extra information and seeing how its received by the platform team.
(In reply to comment #2) > === Approach 1: Retain the current ICPartition types, and have the plug-in's > examine the multi-line or single-line partitions when they are invoked in > order to alter their behaviour as appropriate. > > This works fine but is working around some of the editor architecture. Could you give me a hint where this is working around the editor architecture? We have probably already talked about it, but I just can't remember ;-) > I've experimented with introducing updatable state to the > FastCPartitionScanner, and configuring it at CEditor.doSetInput time. This does > the trick but I've not yet understood if this is legitimate with respect to > other document clients. If not I'd intend to look at writing an > IDocumentSetupParticipantExtension that document setup participants could > optionally implement to recieve this extra information and seeing how its > received by the platform team. Having IDocumentSetupParticipantExtension in the platform is the preferred way if we follow approach 2. Although we are not necessarily bound to the IDocumentSetupParticipant mechanism, clients creating and using a document directly through the IFileBuffer infrastructure would not get the project specific partitioning in that case.
(In reply to comment #3) > Could you give me a hint where this is working around the editor architecture? > We have probably already talked about it, but I just can't remember ;-) its that when you have a single partition type for e.g. multiline comments, then each tool (scanner, autoedit etc.) must include code for switching between plain behaviours and doc-style comment behaviours. For example, the original prototype documentation-comment scanner maintained internal state (switched on calls to setRange) for determining the default token type, and also for referring to from individual rules that might be doc-style comment specific. It was also needed to have a slightly-customized damage-repairer in order to correctly handle changes within the single-typed partition that would change its entire presentation (e.g. /* -> /** or /*! -> /*). There were similar checks for swapping behaviours in other tools. > Having IDocumentSetupParticipantExtension in the platform is the preferred way > if we follow approach 2. > Although we are not necessarily bound to the IDocumentSetupParticipant > mechanism, clients creating and using a document directly through the > IFileBuffer infrastructure would not get the project specific partitioning in > that case. ok, thanks. Is it correct to say there aren't any clients that take this route in CDT at the moment? Maybe having CTextTools methods related to this take an additional parameter for the documentation-comment-family that could be omitted/null would be the way to go (?).
(In reply to comment #4) > (In reply to comment #3) > > Could you give me a hint where this is working around the editor architecture? > > We have probably already talked about it, but I just can't remember ;-) > its that when you have a single partition type for e.g. multiline comments, > then each tool (scanner, autoedit etc.) must include code for switching between > plain behaviours and doc-style comment behaviours. > For example, the original prototype documentation-comment scanner maintained > internal state (switched on calls to setRange) for determining the default > token type, and also for referring to from individual rules that might be > doc-style comment specific. It was also needed to have a slightly-customized > damage-repairer in order to correctly handle changes within the single-typed > partition that would change its entire presentation (e.g. /* -> /** or /*! -> > /*). > There were similar checks for swapping behaviours in other tools. Thanks, I remember now. > > Having IDocumentSetupParticipantExtension in the platform is the preferred way > > if we follow approach 2. > > Although we are not necessarily bound to the IDocumentSetupParticipant > > mechanism, clients creating and using a document directly through the > > IFileBuffer infrastructure would not get the project specific partitioning in > > that case. > ok, thanks. Is it correct to say there aren't any clients that take this route > in CDT at the moment? CSourceHover is such a client, but that can be handled. > Maybe having CTextTools methods related to this take an > additional parameter for the documentation-comment-family that could be > omitted/null would be the way to go (?). Yes, I think that would be the way to go. BTW, do you intend to enhance the syntax coloring preference page with doc-specific highlightings, too?
> BTW, do you intend to enhance the syntax coloring preference page with > doc-specific highlightings, too? I'm unsure about this at the moment, it would certainly be later in the plan if so. I've raised 208881 on platform-text to start discussion about the IDocumentSetupParticipantExtension.
*** Bug 23545 has been marked as a duplicate of this bug. ***
*** Bug 24686 has been marked as a duplicate of this bug. ***
Created attachment 82661 [details] patch for discussion hi, The attached patch is a work-in-progress based upon approach (2) from above. It includes the potential patch for platform-text. There is early support for doxygen, and toy support for doc++ (just to show an alternative). These both live in the ui plug-in at the moment for convenience. There is still work to do in * adding further tests * setting of documentation comment owner property and preference page UI needs tidying up, and possibly moving to a more appropriate location * only one proposal computer is allowed via the IDocViewerConfiguration, I'm wondering if it really makes sense to attach them here, maybe its best to use the existing completion proposal computer extension point and allow an optional specification of documentation comment owner ID I thought its worth specifying some items not in the scope of this bugzilla: * documentation comment validation and problem marker generation * smarter tag content-assist (e.g. @see could consult the index for proposals as JDT does). I don't think the patch precludes this - it just doesn't help here Any feedback would be very appreciated, the patch is getting quite large so if we had an agreement on the approach I could split it into smaller parts. thanks, Andrew
(In reply to comment #9) Andrew, sorry for the late reply. I was sick last week. I just browsed through the patch and it looks very good to me.
thanks very much - I've also been out of office, but hope to pick this up again as soon as possible.
Created attachment 87661 [details] catches up with HEAD
Doug, Anton, could I ask what you'd think about having Doxygen support as part of the UI plug-in? Doug, a bit of background is that this patch adds a framework for pluggable documentation support, and an abstract 'generic' support that should form a basis for different tool plug-ins (e.g. most tools use @tags). The Doxygen support would be the only choosable plug-in if it were to go into the UI.
We've had numerous requests for doxygen support over the years so anything we can do in that area would be very welcome. No one's mentioned other documentation tools so I have no problem giving doxygen most of the focus. But having an open architecture to plug-in others would open the door.
(In reply to comment #13) > Doug, Anton, could I ask what you'd think about having Doxygen support as part > of the UI plug-in? +1 for Doxygen. It seems to be the most popular documentation tool.
Created attachment 89334 [details] patch applied to HEAD thanks, I've applied the above patch to HEAD (It requires the new M5 build to compile)
marking as FIXED
uh, did this get put through an IP review?
(In reply to comment #18) > uh, did this get put through an IP review? I wrote all the code (other than some utilities cloned from JDT) while having committer status. I thought/think this means it doesn't differ from any other large patches I've committed in the past?
Sorry Andrew, I was looking at patch size instead of who attached the patch. Of course you are correct. This is fine. And thank you for this! Doxygen support is something people have been asking for a long time. We'll have to put together a demo on how to use it. Cheers. Doug.
(In reply to comment #20) no problem :), after a panicked re-read of the IP policy I'm just relieved there wasn't a rule I'd missed I'll add some screenshots to the New & Noteworthy wiki
(In reply to comment #21) > (In reply to comment #20) > no problem :), after a panicked re-read of the IP policy I'm just relieved > there wasn't a rule I'd missed > > I'll add some screenshots to the New & Noteworthy wiki Are there any tutorials/advices for using doxygen support inside CDT?
