CDT/Obsolete/C editor enhancements/Documentation support

This is a problem page. Please treat it as a discussion page and feel free to insert your comments anywhere. My open questions are in bold--Tomasz Wesołowski 16:46, 10 May 2010 (UTC)

Description

Embedding documentation in the code in C++ is neither as popular as in Java nor standardised as Javadoc is, but good coding standards encourage documenting the code in an organized way. The most known syntax is probably Doxygen syntax used by the tool of the same name for purposes of external documentation generation. It has the advantage of being clearly readable also in code, so it can be used even without a generator. However, other solutions also exist and the IDE should be able to handle them, too. This has to be included in the design.

Eclipse doesn't really offer any support for easing the access to such documentation for the programmer (as JDT does for Javadoc). The only support at the moment is to display raw comments next to a definition in hovers. There's clearly a lot of place for improvement here.

Ranking

Category: navigation

Importance: 3/5 --Tomasz Wesołowski 17:39, 8 May 2010 (UTC)

4/5 --Tobias Hahn 09:43, 18 May 2010 (UTC)

3/5 --Jens Elmenthaler

Please append your opinion here.

Solution

A possible solution would be to add Documentation to AST nodes. (is it done like this in JDT?)

There are several things to consider in this case:

• How the Documentation is stored (probably in an abstract, syntax-independent manner)
• How the Documentation is acquired (a parser for every supported syntax)
• How the Documentation is presented (different places)

Parsers

This list probably can be extended. Suggestions?.

Doxygen

A parser for Doxygen syntax is probably the most important thing to do.

Raw comments

As a fallback, when no known syntax is detected, the Documentation model could be populated in a heuristic way, treating raw comments as documentation body and - optionally - looking for patterns (e.g. names of other methods embedded in a comments could be automagically converted to links).

Providers

Java has the possibility to introduce Javadoc documentation not only by parsing it in code, but also from acquiring it from external sources. Would it be feasible to give such possibility in CDT? If yes, how exactly? What could the sources be?

Possibly, this won't be necessary. C++ libraries usually come with precompiled binaries and header files. Headers are available in plaintext and the preferred, standard way for providing documentation for them is to embed it inside. The parser can then get the documentation along with the header's AST. Therefore, external documentation providing mechanism may be redundant for CDT.

Is this right? Or is there a need for such a mechanism? Suggestions appreciated.

Context Assist

Context Assist is probably the most important place to display documentation information. In JDT, it is done in a clever manner - by displaying a box with highlighted proposal's documentation next to the context assist window.

CDT would gain much by introducing a similar feature.

Hovers

Currently, hovers display documentation in the form of raw comment. When having a structured documentation infrastructure, a next step would be to augment them to contain formatted documentation with active links.

Documentation View

As in JDT, it is also handful to have a view dedicated to see the documentation for a symbol under the cursor.

Jens Elmenthaler I have written a basic doxygen parser and a Doc view. The Doc view is a copy of the Javadoc view, adapted to use the CDT AST/Index. I would happily give it away.

References

Bug 180141 requests Doxygen support.