Re: patch for g_nullify_pointer() and friends

[Tim Janik <timj gtk org>]

On 6 Aug 2001, Owen Taylor wrote:

> > > Please, can we go to inline docs for GObject? They help a _lot_
> > > in making sure that when you add an API point, you document
> > > it, and when you change an entry point, you update the docs.
> > > Something that doesn't seem to be happening in GObject.
> > 
> > the reason for GObject having lesser docs is not at all related
> > to them being inlined or not. it's a matter of me having the time
> > to do them (and implementation has higher priority here) or
> > someone else volounteering to provide some (that i'd go over,
> > fixup and commit then). Eric Lemings has helped me out here for
> > a while, unfortunately he stopped sending in docs at some point
> > (not that the stuff to cover in those docs would be exactly easy).
> 
> Writing docs should be an integral point of writing an API.
> Without accompanying docs a function is neither correct or
> incorrect; the docs define the contract between the caller and
> the function. Without docs, there is no way to know whether
> something that happens as a result of a function is a) an
> intentional and guaranteed action b) an irrelevant side effect c)
> a bug.

while i basically agree here, since you're talking about the very
first thing to know about API docs, i certainly do have an idea
about my function effects being atributed to a), b) or c).
docs are a matter to carry that knowledge across to API users and
for future reference, but i don't buy into the idea of putting
much energy into function docs untill an API has settled especially
if time is limited and depending on the function, it may take me
as long or longer to write the docs as it takes to write the function
itself.
yes, i'm aware that some people out there think that first you should
document every single bit of an API/program and then go ahead
implementing it, risking that some day you get stuck on a perfect suite
of docs and specs without a single line of code. fine, those people
get to keep their opinion and i just don't join their camp. instead,
i'm usually pursuing the following steps:
- write out the concepts to be implemented/deploeyd in code
- implement ideally self-documenting clean code along the planned concepts.
  here, indeed, assertments, code style etc. does matter, otherwise you
  don't catch invalid costrains and don't gain self-documenting clean code.
- rehash/refine concepts that didn't workout in implementation
- write user-docs for a settled API

> Having good docs for every function is far more important that
> g_return_if_fail() statements or indentation style.  I've been
> routinely asking people to resubmit patches without docs

> At the point where you implement a public entry point to a
> library, you know what the function is meant to do -- isn't it
> easier to write that down at that point rather than having to
> figure it out (or someone else having to figure it out) later?

that depends, if the API is to be undergoing two or three major
overhauls as we had it with the type system, you may very well
double time requirements at each stage. i don't have sacks of
throw-away time laying around in my appartement.

> Docs are one of the many things that are is easier to as you go
> along rather than building up a huge task that must be done
> later.

a matter of opinion.

> 
> Regards,
>                                         Owen
> 

---
ciaoTJ