Re: Public methods description should be in header files

[Pascal Bourguignon]

> From: Nicola Pero <address@hidden>
> Date: Mon, 14 Oct 2002 00:51:29 +0100 (BST)
> 
> 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.

At least,  in emacs you  can M-x w3-fetch  or M-x w3-find-file  a HTML
doc.  It's worse when it's in PDF or RTF.


But  I  agree  with the  point:  better  to  have  the source  of  the
documentation of an API in the header files.

> 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.

Yes.
 
> 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.

>From   the  .m   you   can  extract   the   documentation  about   the
implementation, road-maps  and design  notes for developpers  who will
further work  on the implementation.   But effectively, the  source of
the public documentation of the API should be in the headers.

> 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.


-- 
__Pascal_Bourguignon__                   http://www.informatimago.com/
----------------------------------------------------------------------
 The name is Baud,...... James Baud.