On Mon, 25 Oct 2010 15:10:30 +0800 Brian Wang <brian.wang.0...@gmail.com> said:
> On Mon, Oct 25, 2010 at 2:19 PM, Carsten Haitzler <ras...@rasterman.com> > 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. > > Count me in as a novice EFL user. This is how I find the functions I need: > 1. Look into /usr/include/xxx/xxx.h > 2. If the header doesn't explain itself well, I'll google the > function. Normally, the auto-generated doc goes to the top of the > search results. However, sometimes it's buried in the search results. > > IMHO, put docs in the source and let doxygen generate beautifully > formatted HTML. Put the URL of the auto-generated docs of the library > on the top of the header file to make it easier to find. If the > naming of the API is somehow confusing, simple docs in the header file > help too. > > Reading doxygen comments isn't exactly a quick read and it doesn't > provide linking in the raw form. Probably some vim plugins would > help... Thus, cluttering the header file with doxygen comments will > make the header file more difficult to read. > > By the way, I tried 'make pdf' and the resulting PDF doc is kind of > ugly, font-wise. Is it a latex thing or is it because of my system > setup? Beautiful doxygen-based PDF doc files are good too when I go > offline... > > That's my two cents. the html docs should work offline too... just bring up index.html in a browser. -- ------------- 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
