KDE libs documentation policy

[John Ratke]

Brad Hards wrote:

>-----BEGIN PGP SIGNED MESSAGE-----
>Hash: SHA1
>
>On Sun, 05 Oct 2003 13:46 pm, Benjamin Meyer wrote:
>  
>
>>I have noticed a lot of activity on improving the documentation of the
>>classes in kdelibs and was curious if there was an official policy for the
>>docs of the classes in kdelibs and if not, would there be interest in
>>making an official policy.
>>    
>>
>I'd definatly like an official policy. As one of the people that's been doing 
>some work in this area, I'd suggest:
>1.  enum's have to be overviewed, and each enumerated value has to be 
>explained.
>2. Order is important, or readability is trashed. I've been using @brief, 
>detailed explanation, @param's, @return, @see, @author, @since.
>3. Examples are A Good Thing.
>4. Every UI element needs a picture.
>5. Try to avoid humour and exclamation marks.
>6. "make apidox" before you commit any code.
>  
>
I agree, and also let's add outlawing use of "iff" as a short hand.    
It is used to mean "if blah true, else false", but it is confusing and 
looks like a type-o.  As seen in ktoolbar.h:

@return @p true iff button is on and is a toggle button

As Ben said earlier, we should just mention one case (usually the true 
case), so that should be changed to:

@return @p true if button is on and is a toggle button


Thanks,

-John