[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Public methods description should be in header files

From: Richard Frith-Macdonald
Subject: Re: Public methods description should be in header files
Date: Mon, 14 Oct 2002 15:22:52 +0100

On Monday, October 14, 2002, at 12:44  pm, Nicola Pero wrote:

As I understand it you are basically saying that you want the source of all documentation to be in header files and nowhere else, basically because you like the ease of reading them in emacs, but also perhaps for idealistic reasons of separation of interface and implementation, and conflation of
documentation with interface.

Not all documentation has to be in headers ... all public documentation
has to be in headers; documentation about implementation details and
library internals is to be in sources.

But yes - this is my main point - the headers declare the available public library API to the compilers and programmers using it so it's most natural
to have the documentation about the public library API there.

I think the purpose of header files is to declare interface to the compiler, and making human beings use them is fundamentally a little wrong, as it is
making the human conform to the needs of the machine.
Sure, programmers have to conform to the system all the time,
but that's a necessary compromise, not a virtue. Only habit makes it seem natural -
documentation is not the same thing as interface.
Pretty much all major software systems have separate documentation, because most
people find that easier than looking through source/headers.

However, I see that as a fairly minor point. My concern is with getting people to write documentation ... not really an issue in your case since you are very
good at writing it.

I want to keep documentation primarily in source (but allowing headers) because it's easier for me to write it there and I think that's true for others too, but I would be quite happy to write stuff in the source and have you write stuff in
the headers ... makes no difference to me (or to autogsdoc generated

The downside is that it would likely generate duplicated documentation ...

has it already ?  NSDebug.m contains my original documentation of the
GSDebugAlloc* functions (which I didn't put there but it's now there), and
I see you added new documentation for the same functions in NSDebug.h.

Sorry ... I will have moved that around a while back ... before I knew you wanted to read your documentation in the header files. I won't do that again.

Not a great problem for now, but might become a problem as the
documentation grows.

When I first thought about that, I was concerned ...  When I was first
thinking about generating documentation, I thought it would be nice to
provide simple comments in headers with more in-depth stuff in the
source code, but duplication was an obvious possibility -

My first thought was to generate a warning if this occurred.
My second was ... does it really matter if a little duplication occurs?

I concluded that the best thing to do was try it and see ... if it turns
out to be a real problem, the software could warn, or we could try other

reply via email to

[Prev in Thread] Current Thread [Next in Thread]