Re: Public methods description should be in header files

[Nicola Pero]

I feel we had this dicussion already, and you already knew I'm opposed to
having public documentation in private .m files.

> > Everyone having the headers installed can read the NSSavePanel.h; andthe
> > headers are installed by default, and bundled by default with the
> > packages; while to read the NSSavePanel.m file you need the library source
> > code, which is not installed by default, and if you're getting precompiled
> > binaries, you need to download separately, and it contains actually a lot
> > of implementation details and code which the user needs not to know and
> > read about, as users not knowing how to use a class are notoriously
> > confused by not knowing what is public and what is private.
> 
> As he's put the info in the documentation ... which is where users should
> be looking for it,  I think the above argument is misguided.

No - I don't see what's wrong with users reading it in header files.

I much prefer reading header files (which can be opened, searched,
indexed, cross-referenced etc from the same program - emacs - that I use
to write my own code) than reading html references, which require a
separate program to be started, and require switching continuosly between
the two different programs, and pasting, copying and moving stuff between
the two programs.

When I read source code which uses a library I don't know, I check the
library headers, and read the documentation in the headers - it takes a
second from inside emacs.  I'm too lazy to go around searching on the web
(or on the filesystem) for html documentation for the library, start a
separate browser, search for the page I need, copy&paste what I'm looking
for in the find prompt, and then read it.  Particularly if I'm working via
a command line terminal, where in your setup I'd have to read
documentation using lynx, and switching, and pasting, between emacs and
lynx on the same non-graphical terminal is cumbersome to say the least.


> > Comments explaining public methods _must_ be in public header files where
> > the methods are publicly declared, and where developers using the library
> > can find/read them.
> 
> Information on public methods must be in the documentation ...
> Having it in the headers too ought to be pretty irrelevant.

The source files are not available when the library is installed.  I don't
want to stop my editor and start a separate browser just to read the
explanation of what a method does.  So I'd say having them in headers is
relevant, since if they are in headers, I can read them, else, I can't.

If other users use graphical terminals and prefer to read html reference,
I'm ok with that - we can run autogsdoc and generate html reference for
them, and install it. :-)

There are definitely cases in which I feel I want to start my graphical
browser and read the documentation comfortably and prettily formatted from
top to bottom, and where autogsdoc is *extremely* useful, but that's not
the only way I read the doc.

 
> While I obviously cannot speak for Adam, I can think of two reasons for
> moving from header to source.
> 
> 1. (This one I strongly believe myself) If the source comments for the
> documentation are stored in the .m rather than the .h files, library 
> developers
> (working on the GNUstep code itself) are more likely to keep them up to 
> date.

Up to date ... ?  The API is not supposed to change.  Changing the
implementation of a method in such a way that it behaves differently to
the caller can have a lot of complicated and far reaching consequences for
the gnustep-base or gnustep-gui libraries, so should be quite a rare
event, and a lot of thought must be put into before doing it ... in those
cases you should of course document the changes - but these cases
are/should be the exceptions, not the rule.

 
> 2. (I think a weaker reason) Removing comments from the headers should
> encourage people to read the documentation, showing them that there is a
> single location for reference information.

Are you saying that you want to hide documentation from the headers
because otherwise people might be able to read it without (horror) having
to use your autogsdoc tool ?

I hate the feeling that you are just making a religious crusade against
standard practice of putting comments in headers because you want to force
people to use your autogsdoc tool.

We should be trying to make the documentation available to them by any
means we have, and by all possible channels, not hiding it in order to
force them to use the only 'true' way of reading the documentation (which
would be autogsdoc I suppose).


> > I'd even say it should be in our coding standards (if it's not there
> > already) ... every public method (actually, everything :-)) declared in a
> > public header file should have a corresponding public comment in that same
> > header file explaining what the method does - and how to use it.
> 
> Well, I agree that we should document all public methods ... but I think that
> the place for people to read that is in the documentation.  I don't think it
> is good if our users think they have to read both the documentation *and* the
> headers.

The 'documentation' (by which I suppose you mean the output of your
autogsdoc tool) should then just be generated from the headers.

Reading the documentation or the headers should be the same - they should
contain the same information - users preferring html can read the doc,
users preferring the headers can read the headers.

I'm still not convinced by the fact that your autogsdoc tool is parsing .m
files, since in my opinion, there should be a strict mapping public
headers <--> public documentation - generating documentation from headers
is just a way of converting the comments (and declarations) in the headers
into a different format ... if something is declared/commented in a .m
file, it's precisely because it's private, so no documentation from it is
normally to be generated.  But we already had this discussion.

It looks like we are totally disagreeing, and I'm already enough tired by
our previous discussion on logging, so I don't want to get into a long
argument, and I will refrain from any further comments.

But please record my disagreement (which is nothing new to you I suppose).

I don't think I'll write any (more) reference documentation if it is
managed in this way.