Re: [E-devel] efl documentation (for 1.0.0)

[Carsten H. (T. R. <ra...@ra...>]

On Fri, 22 Oct 2010 07:05:09 -0200 Gustavo Sverzut Barbieri
<bar...@pr...> said:

> On Friday, October 22, 2010, Cedric BAIL <ced...@fr...> wrote:
> > On Fri, Oct 22, 2010 at 7:22 AM, Carsten Haitzler <ra...@ra...>
> > wrote:
> >> ok as a general thing. this isn't any api break.
> >>
> >> doxyegen doc comments. should they go in .c files or in .h files? good
> >> question. eet has it all in Eet.h. the rest of efl has it in .c files. a
> >> good case has been made for it being in .h files instead of .c - that
> >> developers actually do read the .h files and then dont see the docs. they
> >> need to go get the src separately OR find the separately generated docs.
> >> having it all there in 1 place already shipped and installed is useful as
> >> docs are ready to read without needing to find the pretty generated html
> >> ones (or man pages). another bonus - it's instantly obvious what functions
> >> are and are not documented.
> >>
> >> what do people think? move docs to .h file(s)? (its really mostly a
> >> mechanical thing).
> >
> > It make a lot of sense to have the doc in the public header indeed. So
> > I would vote for that too.
> 
> -1 as it gets out of sync much easier, makes .h cluttered to be read
> by humans (elementary and evas are already bad)

aaah. and this is actually the point made for having it there. if efl is
released 1.0 - it gains many new "novice efl users". they NEED docs. they are
not experienced. they are not after a shorthand reference of function names.
the first place they look is the header files and they are not finding the docs
there. so for us few experienced people they get cluttered - and that was part
of the consensus. but when we are outnumbered 100:1 with "novices" looking for
info... then this changes the view a bit - and the case has been made to me
that this is actually happening already. we just don't know about it happening.
thus this email about it.

so far i'd say the opinions are about evenly divided here. that makes this
pretty much a "6 or half a dozen" change so far.

-- 
------------- Codito, ergo sum - "I code, therefore I am" --------------
The Rasterman (Carsten Haitzler)    ra...@ra...