[cdt-dev] Red Hat's Text Hover work.

[Chris Moller <cmoller@xxxxxxxxxx>]

At the request of a couple of people, the following is a fairly detailed 
description of the hoverhelp code I've put together.  The only caveat is 
that while I _think_ my brief comments regarding the architectural 
relationship between my code and CDT are correct, I don't guarantee it. 
 (I have exactly the same experience in Eclipse internals as I do in 
Java -- damn little.  (I code Java using the "If only it were C." method.))

Chris Moller
Senior Hacker
Red Hat, Inc.
-------------------------------------------------------------------------


The API Checking capability -- otherwise referred to as the CDT
HoverHelp capability -- provides a mechanism whereby when a user
positions the pointer over a "known" text string, a short description of
the significance that string is presented.

The typical application of this is when the text string identified
corresponds to the name of a C library function.  For example, given the
non-functional example code

================================================================

#include <stdio.h>

main()
{
         GdkDrawable* re = gdk_drawable_ref();
         GtkWidget * hs = gtk_hscrollbar_new();
         char * txt = strdup("hjgjhhgfhgf");
         int kk = strlen("jjjj");
         fprintf(stderr, "stuff\n");
         qsort();
}

=================================================================

if the pointer is positioned over the libc function name "strlen", the
following information will be displayed:

----------------------------------------------------------------------

#include <string.h>

size_t strlen(const char *s)

The strlen function returns the length of the null-terminated string
s in bytes.  (In other words, it returns the offset of the terminating null

-----------------------------------------------------------------------

Similarly, positioning the pointer over the other example functions
(gdk_drawable_ref(), etc.) will provide a short description of those
functions.


This capability relies on the presence of one or more Java "property"
files containing information pertaining to the various library
functions.  E.g. the property file associated with glibc contains the
following entries for the strlen() function:

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

strlen.Name:      strlen
strlen.Headers:   string.h
strlen.Type:      size_t
strlen.Prototype: const char *s
strlen.Summary: The strlen function returns the length of the
null-terminated \
string s in bytes.  (In other words, it returns the offset of the \
terminating null character within the array.)
strlen.Synopsis: To be added.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

At the present time, such property files exist for the standard C glibc
library, the GTK+ (including GDK and GDK-pixbuf), and X11 (including
Xlib, Xt, Xaw, Xmu, and others) libraries.  Other libraries may be
added as they are identified as being useful.

In addition, nothing precludes addition of "custom" property files
created in conjunction with a particular programming effort.  For
example, a property file could be devised for gcc, allowing gcc
programmers to see the characteristics of internal gcc functions.

Further, there is nothing to preclude adding information pertaining to
programming objects other than functions.  Descriptions of structures,
unions, enums, typedefs, etc., could, with fairly little additional
effort, be added to the property files, and perhaps this could be
implemented in the future.


At present, there are three methods for generating property files from
primary sources.  The first, used for the glibc descriptions, uses a
custom written regex-based C program to parse the texinfo files
accompanying the glibc distribution.  The GTK+ family property files are
created using an extension of a Perl program provided in the gtk-doc
package.  This mechanism extracts tagged information from the GTK+
source code, as well as information contained in external files included
in the GTK+ distribution.  The X11 property files are extracted from the
X11 NROFF-format man pages accompanying the XFree86 distribution by a
custom Perl program.

Clearly, the creation of property files is hindered by the use of wildly
disparate documentation paradigms requiring methods unique to each to
extract relevant information.  In this regard, it would greatly benefit
the development community to adopt one (or a few) standard documentation
methods, preferrably based on semantically tagged textual elements.  The
GNU "texinfo" format, used in glibc, is an example of an easily
manipulated format, and at least one package -- called "doxygen" --
exists that appears to offer similar a characteristic.


At present, the HoverHelp property files, either per se, or compressed
into jar files, must be located in one of a number of specific
directories identified by a hard-coded path string.  (Making this path
string user-settable is a current effort.)  The use of a search path to
locate property files will allow updated property files associated with,
e,g., newer releases of a particular library, to supplant obsolete
property files perhaps present as part of the CDT distribution.  (A
protocol for this process has yet to be devised.)  The use of a path
also permits the custom property files mentioned above to be used.



Architecturally, all of the foregoing is implemented as a patch against 
CDT affecting extension point textHovers and involving a small 
collection of new Java classes in org.eclipse.cdt.ui, two new classes in 
org.eclipse.cdt.core, plus a few minor modifications to 
plugin.properties and plugin.xml in those directories.

This HoverHelp capability was developed to be invoked in
DefaultCEditorTextHover.getHoverInfo().  This, however, appears to 
present a problem as, historically, getHoverInfo() appears to have been 
used to provide text completion instead of, or in addition to, hover 
text.  This ambiguity will require resolution.



Potential future efforts in the development of this capability may include:

1.  Identifying useful standard libraries for which to add corresponding
property files, possibly devising custom mechanisms for doing so.

2.  Adding the capability to display non-function information such as
structures, enums, etc.

3. If one or more standard documentation systems can be identified,
providing within Eclipse a means of creating corresponding property files.

4. Devising protocols (perhaps based on RPM) for automatically updating
library property files as newer revisions of the various supported
libraries are released.

5. reimplementing the capability as a plugin.