On Mon, 25 Oct 2010 08:28:58 +0200 (CEST) Vincent Torri <vto...@univ-evry.fr> said:
> > > On Mon, 25 Oct 2010, Carsten Haitzler (The Rasterman) wrote: > > > 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. > > some of us whant the doc in headers, other in source. what about putting > doc in header AND source code ? :) > > Vincent > > PS: you did see the smiley, right ? i slap your smiley /me throws the cow back to vtorri. -- ------------- 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
