Re: Public methods description should be in header files

[Pascal Bourguignon]

> From: Richard Frith-Macdonald <address@hidden>
> Date: Mon, 14 Oct 2002 06:55:10 +0100
> [...]
> 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*

I would agree here if the header installed would be generated from the
source  header and gathering  the API  documentation imbeded  into the
source .m comments...


For  my own  projects, I  got  used to  open always  two windows:  one
header, one implementation, and  to keep API documentation/comments in
the header  file and implementation notes  and implementation comments
in  the implementation  file.  Then  I  can easily  open other  header
windows over the header window of the  module I work on when I need to
refer to these other headers and their documentation.


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

Yes, nice.


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

Then, I  would say, why not put  the header data into  the source too,
and have a tool to extract it and generate the header files?

Don't  you  have  the header  file  on  screen  when  you work  on  an
implementation anyway?



In anycase, I  agree that the header of a  class and the documentation
of  the  API   of  that  class  should  basically   contain  the  same
information.

The documentation can contain  in addition "informal" descriptions and
"cook-book"  items though,  and  there could  be global  documentation
explaining  the inter-relationship  between the  various parts  of the
systems, that would not fit into the interface of one class. Hence the
use for the documentation.  But  once you know this general info, it's
better to have all the API  documentation in the headers that you have
under your eyes anywhay when you program.

If it's written  first into an implementation file, we  have to find a
way  to  migrate it  into  the header  files  that  are installed  and
published.


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