On Mon, Oct 25, 2010 at 3:15 PM, Carsten Haitzler <ras...@rasterman.com> wrote: > 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.
Yes, it works! Cool! brian > > -- > ------------- Codito, ergo sum - "I code, therefore I am" -------------- > The Rasterman (Carsten Haitzler) ras...@rasterman.com > > -- brian ------------------ Cool-Karaoke - The smallest recording studio, in your palm, open-sourced http://cool-idea.com.tw/ iMaGiNaTiOn iS mOrE iMpOrTaNt tHaN kNoWlEdGe ------------------------------------------------------------------------------ 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
