[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: |
Pascal Bourguignon |
Subject: |
Re: Public methods description should be in header files |
Date: |
Mon, 14 Oct 2002 05:05:15 +0200 (CEST) |
> 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.
- Public methods description should be in header files, Nicola Pero, 2002/10/12
- Re: Public methods description should be in header files, Richard Frith-Macdonald, 2002/10/13
- Re: Public methods description should be in header files,
Pascal Bourguignon <=
- Re: Public methods description should be in header files, Richard Frith-Macdonald, 2002/10/14
- Re: Public methods description should be in header files, Richard Frith-Macdonald, 2002/10/14
- Re: Public methods description should be in header files, Nicola Pero, 2002/10/14
- Re: Public methods description should be in header files, Richard Frith-Macdonald, 2002/10/14
- Re: Public methods description should be in header files, Nicola Pero, 2002/10/14
- Re: Public methods description should be in header files, Richard Frith-Macdonald, 2002/10/14
- Re: Public methods description should be in header files, Adam Fedor, 2002/10/14
- Re: Public methods description should be in header files, Pascal Bourguignon, 2002/10/14
- Re: Public methods description should be in header files, Pascal Bourguignon, 2002/10/14