Re: Standard header format.

["Steven T. Hatton" <hattons at globalsymmetry dot com>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Tuesday 08 June 2004 01:57, llewelly@xmission.com wrote:
> "Steven T. Hatton" <hattons@globalsymmetry.com> writes:

> > for example, then looking at the "standard headers" would be a worthwhile
> > means of determining what is provided by the Standard Library. I believe
> > the people who have suggested looking at the Standard Headers were
> > expecting me to find them in the form presented above.  I am not saying
> > they /should/ expect that.  I'm saying they /do/ expect that.
>
> If the above is intended to inform programmers as the the interface of
>     the library, it belongs in the *documentation*, not in the header
>     files. Most programmers only look at the header files when the
>     documentation is woefully inadequate.

I haven't taken a scientific poll, but my experience has been most C++ 
programmers with whom I have discussed this issue have been been quite 
forceful in stating their belief that header files should present the API to 
the user, and that should serve as a human readable reference for the user of 
the API.  Most API documentation I've seen for C++ is either the Doxygen 
output from processing the header files, or the header files themselves.  
When it is the Doxygen output, it is typically nothing more than an HTML 
rendering of the header file.  The only difference between looking at the 
html and the header file is typically that the header file is harder on the 
eyes because of all the markup in the comments.

Note that the header file shown here: 
http://xml.apache.org/xerces-c/apiDocs/DOMDocument_8hpp-source.html

has been stripped of the the comments used to generate this:
http://xml.apache.org/xerces-c/apiDocs/classDOMDocument.html

The same file in the installed code base contains all the comments used to 
generate the html.

More examples of the same approach.
http://artis.imag.fr/Members/Yannick.Legoc/X3D/doc/html/a00789.html#a17
http://doc.coin3d.org/Coin/classSoMaterialBinding.html
http://lxr.kde.org/source//kdelibs/kdeui/klistview.h
http://developer.kde.org/documentation/library/cvs-api/kdevelop/html/ast_8h-source.html
http://lxr.mozilla.org/seamonkey/source/parser/htmlparser/src/nsDTDUtils.h

>     If a C programmer needs to 
>     know the interface of printf, he looks in the man or info pages
>     for his system's libc. He doesn't look at the header files, which
>     in all frankness he probably can't understand anyway.

If the header files are unintelligible to the user, then they do not present 
the API the use should be expected to use.

>     It should be the same for C++ programmers.

Though it is not a universal practice, it is quite common to consider the 
header files for a C++ application to be both the programmatic and human 
readable declaration of the API. I am quite confident that is Stroustrup's 
meaning when he describes header files as 'adevertising the user interface'.

But this is really a secondary matter.  I specifically want the programmatic 
form of the interface available in electronic form as if it were declared in 
actual header files that look like the headers in the C++ standard. 

Accessing information in documentation and then transcribing it into code is 
an unnecessarily slow process for many purposes such as verifying the order 
in which parameters appear in a method invocation.  The declarations provided 
by the headers listed in the standard could (should) be used to generate code 
completion templates (distinct from the C++ sense of template<>).

I have these questions about this approach:

Would it provide the functionality I want? That is: 

Scope sensitive, declaration aware, code completion, to include adding 
necessary headers and using declarations. (It seems obvious to me that it 
would, but I could be wrong)

Edit-time error detection of virtually any error detectable by the compiler. 
(that seems far more challenging, but not impossible to a good approximation)

How useful would it be to the programmer? (IMO, extremely useful.)  

Could it be done with libstdc++?  (Yes, in principle.)
Would it be too difficult?
- -- 
Regards,
Steven
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.2 (GNU/Linux)

iD8DBQFAxb/zwX61+IL0QsMRAmK5AJoDpO4WSNgmRTD5nRy/Q68PgNUFVwCg5dc0
n/W6nKnx+w5qCxiREERtVEU=
=1WJi
-----END PGP SIGNATURE-----