On Fri, 22 Oct 2010 07:05:09 -0200 Gustavo Sverzut Barbieri <barbi...@profusion.mobi> said:
> On Friday, October 22, 2010, Cedric BAIL <cedric.b...@free.fr> wrote: > > On Fri, Oct 22, 2010 at 7:22 AM, Carsten Haitzler <ras...@rasterman.com> > > 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) ras...@rasterman.com ------------------------------------------------------------------------------ Nokia and AT&T present the 2010 Calling All Innovators-North America contest Create new apps & games for the Nokia N8 for consumers in U.S. and Canada $10 million total in prizes - $4M cash, 500 devices, nearly $6M in marketing Develop with Nokia Qt SDK, Web Runtime, or Java and Publish to Ovi Store http://p.sf.net/sfu/nokia-dev2dev _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
