HeaderDoc support

[GoogleCodeExporter]

We should see if we can get HeaderDoc support on pop-up hovers and/or displayed 
in a 
HeaderDoc view. I'm not sure if there's anything we can leverage from CDT for 
this at the 
moment; the partitioner allowed a source file to be split into chunks, but I'm 
not sure of its level 
of support.

Original issue reported on code.google.com by alex.ble...@gmail.com on 24 Jul 2009 at 8:14

[GoogleCodeExporter]

HeaderDoc is documented at Apple:

http://developer.apple.com/darwin/projects/headerdoc/

A HeaderDoc comment is an ordinary C comment with a leading bang:

/*!
 This is headerdoc
 */

It can also have leading * like Java (and it might be preferable for 
ObjectivEClipse to put in the leading * for 
consistency's sake)

/*!
 * This is also headerdoc
 */

Unlike JavaDoc, where the first sentence is used as a one-liner and the 
remainder is used as text, HeaderDoc 
uses @abstract for the one-liner and @description for the full text. You can 
also use other @ keywords, like 
@class, @function, @method, @interface, @protocol to document those types of 
items.

Here's an incomplete list of the headers we should probably support/parse:

* @class ClassName
* @method foo:withBar:andBar:
* @protocol ProtocolName
* @abstract OneLiner for Table of Contents
* @discussion More detailed discussion, possibly multiple lines or following 
text
* @throws ExceptionName
* @param bar The Bar parameter
* @return or @result The Return Value
* @version Version Number (e.g. $Id$ )
* @Updated yyyy-mm-dd When it was last touched
There are others, which we might want to have as keywords for auto-completion, 
but probably leave to a 
subsequent iteration to complete:

* @struct StructName
* @typedef TypeDefName
* @union UnionName
* @var GlobalVarName
* @enum EnumName
* @file FileName
* @framework FrameworkName
* @functiongroup Function Group name (like #pragma mark blocks?)
* @const ConstantName
* @define or @defined HashDef Name
* @field FIeldName (structs etc.)
* @deprecated Deprecated In Version Foo

There's also esoteric support for inclusion in different versions of a product:

* @availabilitymacro DEFINED Shows up as Available In: String if DEFINED is 
defined

Original comment by alex.ble...@gmail.com on 30 Jul 2009 at 8:49

[GoogleCodeExporter]

We could do extra parsing of the comment header whilst we do the parsing - in 
the meantime, we can get it 
out of the translation unit as a string for the comment.

Hovers are contributed via the UI plugin as follows:

 <extension
         point="org.eclipse.cdt.ui.textHovers">
      <hover
            label="%cdocHover"
            description="%cdocHoverDescription"
            class="org.eclipse.cdt.internal.ui.text.c.hover.CDocHover"
            id="org.eclipse.cdt.ui.CDocHover">
      </hover>
      <hover
            label="%sourceHover"
            description="%sourceHoverDescription"
            class="org.eclipse.cdt.internal.ui.text.c.hover.CSourceHover"
            id="org.eclipse.cdt.ui.CSourceHover">
      </hover>
</extension>

The one that's currently used is CSourceHover, which is what gets instantiated 
at the moment. The 
CDocHeader doesn't appear to give anything at present, but it may be possible 
that we can hook into 
delivering the documentation into the help system. The CHelpProviderManager 
maintains a cache of data, 
and it's possible we can just feed the items into there. There is a HelpInfo 
which can contributed Help 
documents

Original comment by alex.ble...@gmail.com on 31 Jul 2009 at 9:21

[GoogleCodeExporter]

For those tracking this bug, I've committed r139 which allows you to put /*! as 
the start of a HeaderDoc 
block, and above a function and a method, generate a HeaderDoc template. I've 
not yet completed the full 
list of HeaderDoc tags, nor does it work above classes (or file headers) at the 
moment. 

This will temporarily affect mouse-overs that will display a standard C header 
and source code, though I'm 
hoping to improve that subsequently.

In order to see this, you'll need to change the document handler to be 
'headerdoc' in the project, by right-
clicking on the project and going to C/C++ General, enabling project specific 
settings, and selecting 
'HeaderDoc' from the drop-down list. 

This will be the default on Mac platforms eventually going forward unless 
anyone objects.

Original comment by alex.ble...@gmail.com on 5 Aug 2009 at 10:08