Re: [PATCH] NSSavePanel.m -beginSheetForDirectory::::::

[Alexander Malmberg]

Fred Kiefer wrote:
> Alexander Malmberg wrote:
> > Fred Kiefer wrote:
> >>
> >>At least for Cocoa these enums are fully documented,
> >
> > Where?
> > [snip wrong place to look]
>
> Where would you expect enumerators to be documented? In the "Types and
> Constants" section not in the "Classes" documentation:
> 
> http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/TypesAndConstants/AppKitTypes.html#//apple_ref/doc/uid/20000019/BAJGDFCH

Ah, duh. :/ Seems unfortunate that the descriptions I read doesn't link
back to this page.

[snip]
> > I suppose you could see the headers, which do specify the integer
> > values, as implicit documentation, but GNUstep doesn't have a "the
> > header is the documentation"-tradition.
> 
> This is a very strange statement, I already did reply to a previous mail
> from Kazu, that I don't have access to any Apple header files. Up to now
> I thought, that my writen word for not using any Apple headers should be
> enough.

This sounds like a misunderstanding. I wasn't talking about apple's
headers, I was talking about GNUstep's headers, and what exactly we
consider part of our public API, and thus what we need to do to make
sure that the integer values of the constants are a part of our public
API.

To give a concrete example, in which of the following cases (in a
hypothetical GNUstep header) would you consider the fact that Foo has
the value 42 to be publically documented?


/* quux1.h */
enum
{
        Foo=42
};


/* quux2.h */
/**
 * This enum is used in the function -quux:, and may have the
 * following values:
 * Foo   Does xyz.
 * ...
 */
enum
{
        Foo=42
};


/* quux3.h */
/**
 * This enum is used in the function -quux:, and may have the
 * following values:
 * Foo (42)  Does xyz.
 * ...
 */
enum
{
        Foo=42
};


In a project with a policy that the public headers are the public
documentation, I'd say that quux1.h would be enough. However, in GNUstep
we have a fair bit of private stuff in public headers, and lots of
public documentation in .m files instead of in headers, so I think we
need quux3.h to make sure that Foo==42 is clearly a part of the public
API and not just an implementation detail.

- Alexander Malmberg