gnustep-dev
[Top][All Lists]
Advanced

[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 06:55:10 +0100

On Monday, October 14, 2002, at 12:51  am, Nicola Pero wrote:

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

I had the impression you thought it was just not particularly
better, rather than you actually being opposed to it.

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

Nothing particularly wrong with that ... as long as the info is available
in the documentation.

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.

Point taken that you actually *like* to read headers ... you can read html from emacs (and you don't have to have the source installed to read html),
but I guess it's not as nice for you as.

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.

You are talking about an ideal world though, where we perfectly document the code when we write the original API. The point about generated documentation is to deal with the real world ... where documentation is non-existent or incomplete and needs to be be written/corrected. In GNUstep in particular, we have a fairly well defined API, and the actual method names don't change, but our understanding of what they should do changes and the implementation gets bugfixes etc. We may
add checking for nil arguments. The behavior may change from trying to
continue gracefully to raising an exception. The method may be made thread-safe. etc etc. Even where there is no functional change to source, the fact that someone makes a bugfix provides them with the opportunity to improve/correct documentation if the source for that documentation is in the same place as the code they are fixing.
Placing documentation is the .m files is *pragmatic*

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.

No. I rather resent the inference you are making... we were talking about a change Adam made, not something I did, and you seem to be implying that I've made some private agreement with him to remove stuff from headers ... that's
simply not true.

All I said was that having a single consistent location for people to look at documentation might have been part of his motivation (and I said I thought
this a weaker reason).  This is completely irrelevant to whether you use
autogsdoc  (which is a great tool :-) ) or not.

I have no real problem with putting comments in headers, and autogsdoc is designed to read comments from *both* headers and source and combine them, with the stuff from the header coming first ... it works very well doing it.

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

Absolutely not ... nobody reads documentation using autogsdoc ... it's used purely to produce documentation. Part of the motivation for writing it was to make it easier to produce the documentation in many formats (I just don't
have time to do more than html now really).

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 understand (and agree in a way with) that argument ... I think our basic disagreement here is on whether to go with an idealised system or a pragmatic
one.

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

This is a great shame.

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.

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

Am I really understanding you correctly?

Are you saying that you don't want to write documentation if documentation is managed by autogsdoc, or are you just saying that you don't want to write
documentation if Adam moves it from header to source, or are you saying
something else entirely?





reply via email to

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