Re: Public methods description should be in header files

[Pascal Bourguignon]

> From: Alexander Malmberg <address@hidden>
> Date: Mon, 14 Oct 2002 02:35:17 +0200
> 
> 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.
> 
> For what it's worth, I agree with Nicola here: I prefer to have public
> documentation in the headers.
> 
> [snip]
> > > 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.
> 
> Well, the current implementations of many things don't work as they're
> "supposed" to work, so I don't think these changes will be that rare
> (yet). IMHO, the documentation (preferably in the headers) should
> document the intended behavior, and changing the implementation to match
> that should be ok (even when it breaks things). This way, changing the
> documentation should happen only rarely and after due consideration, and
> "up-to-date" is meaningless.
> 
> - Alexander Malmberg


Ok,  but  then you  need  also  to know  the  peculiarity  of a  given
implementation.

For example, if the specification is that a function may return a A, a
B or a C, but a certain implementation returns always a B, it could be
usefull to say: 

     
     extern result func();
        /*
            RETURN:       either a A, a B, or a C, depending on the weather.
            IMPLEM-NOTE:  the current implementation only returns a B.
        */



Now, it  could be nice  to have an  header strictly conforming  to the
specified API:

     extern result func();
        /*
            RETURN:       either a A, a B, or a C, depending on the weather.
        */


and an implementation where the specificities are documented:

     result func()
        /*
            IMPLEM-NOTE:  the current implementation only returns a B.
        */
     {
        return B;
     }

and then obtain a documentation that would gather both:


    Function "func"
    ---------------

      result func();

        RETURN:       either a A, a B, or a C, depending on the weather.
        IMPLEM-NOTE:  the current implementation only returns a B.




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