Re: patch for g_nullify_pointer() and friends

[Owen Taylor <otaylor redhat com>]

Tim Janik <timj gtk org> writes:

> On 6 Aug 2001, Owen Taylor wrote:
> 
> > Tim Janik <timj gtk org> writes:
> > 
> > > On 6 Aug 2001, Sven Neumann wrote:
> > > 
> > > > Hi,
> > > > 
> > > > here's a new patch. I stayed with g_nullify_pointer() since I agree
> > > > with Tim on this subject. The GObject additions are implemented as
> > > > functions now and are documented inline. Someone should please check 
> > > > that I found the correct words. The patch also adds a simple test
> > > > case to testgruntime. There should probably be more tests there...
> > > 
> > > a couple minor things:
> > > for gobject.c and friends, i'd like to avoid inline docs, so please
> > > add the docs to docs/reference/gobject/tmp/gobject.sgml.
> 
> > 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.

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?

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.
 
> the reason i do not want them to be inlined there is that i need
> to find my way through the sources which is hard enough already,
> the last thing i need between thread-lock and reentrancy constraint
> maintenance code are huge, comparatively unrelated comment blurbs
> explaining basic concepts. don't read this wrong as "tim doesn't
> want API docs", i just do not want them in the *.[hc] files
> which are huge enough already.

Detailed explanation of concepts can go in the intro sections,
which are in the intro sections. Good docs that record the
contract for each function are much more likely to be accurate
and complete if they are right next to the function, and I think
that a few more arrow keys to move around the file are more than
overbalanced by being able to see exactly what the function was
meant to do clearly set out with each function.

This will especially be true in a few years after you've
forgotten how gtype.c works yourself :-)

I think we've conclusively that inline docs are an effective
technique for making sure that we have decent docs, and I wish
you would reconsider using them for GObject.

Regards,
                                        Owen