Re: [E-devel] efl documentation etc...
I think i do need to get that api documentation, after all :) anybody with a generated apidoc? I kinda want to start dev'ing efl+vala, already have both, just need the api knowhow. -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
i guess that the authors of the binding can help you (see AUTHORS file) Vincent On Fri, Aug 3, 2012 at 8:16 AM, Donn Jeferson R Atienza stroodle...@gmail.com wrote: anyone here who knows how to start development using efl in vala? I have access to vapi files, i just don't know how to use it yet... -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
anyone here who knows how to start development using efl in vala? I have access to vapi files, i just don't know how to use it yet... -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
[E-devel] efl documentation etc...
Is there a way for me to obtain the efl libraries for offline viewing? i tend to dev without a net connection. also, are there any successful vapis for the efl? any attempts? -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
On Wed, Aug 1, 2012 at 6:49 PM, Donn Jeferson R Atienza stroodle...@gmail.com wrote: Is there a way for me to obtain the efl libraries for offline viewing? i tend to dev without a net connection. If you already have efl source code, just go inside the build directory and run make doc, this will generate all documentation locally. If you don't I may do it for you, or anyone with the source on his computer can. also, are there any successful vapis for the efl? any attempts? What is vapi ? -- Cedric BAIL -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
bindings for vala are called vapi files, i have not much knowledge though... check out gnome dev site for details... :) -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
Hello. On 08/01/2012 11:05 AM, Donn Jeferson Atienza wrote: bindings for vala are called vapi files, i have not much knowledge though... check out gnome dev site for details... :) We have vala bindings in BINDINGS/vala in svn. regards Stefan Schmidt -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
Yes we have it! http://trac.enlightenment.org/e/browser/trunk/BINDINGS/vala Daniel Juyung Seo (SeoZ) On Wed, Aug 1, 2012 at 7:20 PM, Stefan Schmidt s.schm...@samsung.com wrote: Hello. On 08/01/2012 11:05 AM, Donn Jeferson Atienza wrote: bindings for vala are called vapi files, i have not much knowledge though... check out gnome dev site for details... :) We have vala bindings in BINDINGS/vala in svn. regards Stefan Schmidt -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
Thank you very much! is there any tutorial on how to set up efl libs for development? right now I'm using geany for vala dev under bodhi linux... i plan to learn cross platform app development using the efl+vala; since elementary went stable recently, i got fired up about it... -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation etc...
On Thu, 2 Aug 2012 10:32:09 +0800 Donn Jeferson Atienza stroodle...@gmail.com said: Thank you very much! is there any tutorial on how to set up efl libs for development? right now I'm using geany for vala dev under bodhi linux... i plan to learn cross platform app development using the efl+vala; since elementary went stable recently, i got fired up about it... hmm i can't help with vala, but i use jed as my editor terminolgy.. because its pretty. :) i just do the usual make stuff :) -- - Codito, ergo sum - I code, therefore I am -- The Rasterman (Carsten Haitzler)ras...@rasterman.com -- Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
[E-devel] EFL documentation
Hello all, ProFUSION, sponsored by Samsung, is starting a documentation project(yes, another one =). This means we'll be going over any pieces of documentation we fell are incomplete or that could use some improvement and give it some work. The EFL though is huge and we could use everyone's help. In this spirit I'd like to kindly ask everyone who commits new code to document it and, even more importantly, whenever you cause a behaviour change remember to change the documentation! Happy coding, Gastal -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation
On Fri, 17 Feb 2012 11:40:38 -0200 Jonas M. Gastal jgas...@profusion.mobi wrote: Hello all, ProFUSION, sponsored by Samsung, is starting a documentation project(yes, another one =). This means we'll be going over any pieces of documentation we fell are incomplete or that could use some improvement and give it some work. The EFL though is huge and we could use everyone's help. In this spirit I'd like to kindly ask everyone who commits new code to document it and, even more importantly, whenever you cause a behaviour change remember to change the documentation! Happy coding, Gastal any chance this will cover ecore-x? there's zero documentation there. -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation
Good stuff! :) Any chance this will cover internals too (maybe as a secondary objective) ? While the public API is generally well documented, internal APIs aren't. I'm referring anyways to the difficulty to understand how to write a new evas engine for example. On Fri, Feb 17, 2012 at 3:22 PM, Michael Blumenkrantz michael.blumenkra...@gmail.com wrote: On Fri, 17 Feb 2012 11:40:38 -0200 Jonas M. Gastal jgas...@profusion.mobi wrote: Hello all, ProFUSION, sponsored by Samsung, is starting a documentation project(yes, another one =). This means we'll be going over any pieces of documentation we fell are incomplete or that could use some improvement and give it some work. The EFL though is huge and we could use everyone's help. In this spirit I'd like to kindly ask everyone who commits new code to document it and, even more importantly, whenever you cause a behaviour change remember to change the documentation! Happy coding, Gastal any chance this will cover ecore-x? there's zero documentation there. -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation
On Fri, Feb 17, 2012 at 6:22 PM, Michael Blumenkrantz michael.blumenkra...@gmail.com wrote: On Fri, 17 Feb 2012 11:40:38 -0200 Jonas M. Gastal jgas...@profusion.mobi wrote: Hello all, ProFUSION, sponsored by Samsung, is starting a documentation project(yes, another one =). This means we'll be going over any pieces of documentation we fell are incomplete or that could use some improvement and give it some work. The EFL though is huge and we could use everyone's help. In this spirit I'd like to kindly ask everyone who commits new code to document it and, even more importantly, whenever you cause a behaviour change remember to change the documentation! Happy coding, Gastal any chance this will cover ecore-x? there's zero documentation there. Unlikely. The plan is to document what application writers see, and they should stay away from Ecore_X. -- Gustavo Sverzut Barbieri http://profusion.mobi embedded systems -- MSN: barbi...@gmail.com Skype: gsbarbieri Mobile: +55 (19) 9225-2202 -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation
On Fri, Feb 17, 2012 at 7:47 PM, Youness Alaoui kakar...@kakaroto.homelinux.net wrote: Good stuff! :) Any chance this will cover internals too (maybe as a secondary objective) ? While the public API is generally well documented, internal APIs aren't. I'm referring anyways to the difficulty to understand how to write a new evas engine for example. No. At least not in this project, here we're focusing on the people that are coming to EFL due Tizen and they are not writing such things. Note it *looks like* we have well documented API. Just rephrasing the API name without _ is not enough (ie: elm_win_title_set() - Sets the title of the window). We needs to document relations (even the most subtle!), side effects, pre and post conditions (when there are such). Last but not least, need examples of real world use cases as not everyone can deduce what to do :-) -- Gustavo Sverzut Barbieri http://profusion.mobi embedded systems -- MSN: barbi...@gmail.com Skype: gsbarbieri Mobile: +55 (19) 9225-2202 -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/ ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation
On Fri, 17 Feb 2012 21:46:27 -0200 Gustavo Sverzut Barbieri barbi...@profusion.mobi wrote: On Fri, Feb 17, 2012 at 7:47 PM, Youness Alaoui kakar...@kakaroto.homelinux.net wrote: Good stuff! :) Any chance this will cover internals too (maybe as a secondary objective) ? While the public API is generally well documented, internal APIs aren't. I'm referring anyways to the difficulty to understand how to write a new evas engine for example. No. At least not in this project, here we're focusing on the people that are coming to EFL due Tizen and they are not writing such things. Note it *looks like* we have well documented API. Just rephrasing the API name without _ is not enough (ie: elm_win_title_set() - Sets the title of the window). We needs to document relations (even the most subtle!), side effects, pre and post conditions (when there are such). Last but not least, need examples of real world use cases as not everyone can deduce what to do :-) I think there is only one real world use case currently implemented for Edje Lua, and it's not open source so I can't share it. I'm working on more stuff that IS open source though. On the other hand, a small part of that real world use case made it into the example script in SVN. The grid of bubbles widget. -- A big old stinking pile of genius that no one wants coz there are too many silver coated monkeys in the world. signature.asc Description: PGP signature -- Virtualization Cloud Management Using Capacity Planning Cloud computing makes use of virtualization - but cloud computing also focuses on allowing computing to be delivered as a service. http://www.accelacomm.com/jaw/sfnl/114/51521223/___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] efl documentation (for 1.0.0)
On Fri, 22 Oct 2010 08:43:17 -0400 Mike Blumenkrantz m...@zentific.com said: On Fri, 22 Oct 2010 10:28:40 -0200 Lucas De Marchi lucas.demar...@profusion.mobi wrote: On Fri, Oct 22, 2010 at 7:05 AM, Gustavo Sverzut Barbieri barbi...@profusion.mobi wrote: 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) -1 too. Header becomes much more difficult to read. Maybe user should be directed to the docs that are automatically generated... Agree. That's the whole point of doxygen. well yes and no - doxygen makes the docs more manager friendly i.e. provides nice formatted printable or html docs with links and prettiness. as such the core of the docs are still the same text be it in the .h or in the html. -- - Codito, ergo sum - I code, therefore I am -- The Rasterman (Carsten Haitzler)ras...@rasterman.com -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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 ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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 ? -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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 ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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. brian 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 ATT 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 -- 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 ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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 ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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 ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Mon, Oct 25, 2010 at 9:15 AM, 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. I actually think that putting in each root header a link to the auto generated doc will help people that are looking at our API. We could also take into account the version when we do a release and point them to the right version of the doc online. This could be automatic. -- Cedric BAIL -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Mon, 25 Oct 2010 09:42:43 +0200 Cedric BAIL cedric.b...@free.fr said: the html docs should work offline too... just bring up index.html in a browser. I actually think that putting in each root header a link to the auto generated doc will help people that are looking at our API. We could also take into account the version when we do a release and point them to the right version of the doc online. This could be automatic. aaah that is indeed an issue yet undiscussed. we auto-generate docs for whatever trunk has. fine until we do evas2.0 or any api break.. as docs wont be wrong - they may just document new features not yet available in your versions of evas/edje/eina/whatever. so as of 1.0 we do NEED to make sure we clearly document as of when a feature is available (after 1.0 next round of features will be 1.1 - so any features and api's added need to be marked as added in 1.1). unless we want to generate new docs per minor version of evas? anyway - still.. the question is being tossed back and forth. we have 2 sides. in .h or not. i ask this. read Eet.h - is that hard to use/read? would you prefer... Ecore.h for example? (actually while i'm at it.. the tonne of eina headers... i'm not too fond of.. but we won't be changing this any time soon methinks). also one other thing. if we put API docs in the public .h - we can separately document internal info in the .c files - it's at least easier to handle doc-wise that trying to put different comment snippets within the same files in different doxygen sections (hell u'd want them in 2 separate documents at the end of the day). -- - Codito, ergo sum - I code, therefore I am -- The Rasterman (Carsten Haitzler)ras...@rasterman.com -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Mon, Oct 25, 2010 at 10:26 AM, Carsten Haitzler ras...@rasterman.com wrote: On Mon, 25 Oct 2010 09:42:43 +0200 Cedric BAIL cedric.b...@free.fr said: the html docs should work offline too... just bring up index.html in a browser. I actually think that putting in each root header a link to the auto generated doc will help people that are looking at our API. We could also take into account the version when we do a release and point them to the right version of the doc online. This could be automatic. aaah that is indeed an issue yet undiscussed. we auto-generate docs for whatever trunk has. fine until we do evas2.0 or any api break.. as docs wont be wrong - they may just document new features not yet available in your versions of evas/edje/eina/whatever. so as of 1.0 we do NEED to make sure we clearly document as of when a feature is available (after 1.0 next round of features will be 1.1 - so any features and api's added need to be marked as added in 1.1). unless we want to generate new docs per minor version of evas? I have no strong opinion on that. The only draw back I see with online docs per minor version, is how search engine would handle them. If we do our job correctly, and have only one version online, people will know by reading the docs when it was added to the EFL. So I am a bit inclined to have only one auto build doc repository, but nothing really strong on that. anyway - still.. the question is being tossed back and forth. we have 2 sides. in .h or not. i ask this. read Eet.h - is that hard to use/read? would you prefer... Ecore.h for example? I tend to think that Eet.h is harder to read, but not only because of the doc, but because all functions are in it, eet_image*, eet_data* and so on. Having only one header per group of function help in that sense. As for Ecore.h, the only think I don't like is when pointer to callback function don't have a name that help understand what they do (I think I did fix all case in that header). (actually while i'm at it.. the tonne of eina headers... i'm not too fond of.. but we won't be changing this any time soon methinks). In fact, my preferred header at the moment are eina :-) Divided by functionalities, with some doc and tutorial where it make sense. also one other thing. if we put API docs in the public .h - we can separately document internal info in the .c files - it's at least easier to handle doc-wise that trying to put different comment snippets within the same files in different doxygen sections (hell u'd want them in 2 separate documents at the end of the day). In eina, we did put the local part from the global part at the top of each .c files and they are already separated from the doxygen point of view. If we where considering adding documentation for the internal, it wouldn't be difficult. -- Cedric BAIL -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Mon, 25 Oct 2010 11:15:42 +0200 Cedric BAIL cedric.b...@free.fr said: On Mon, Oct 25, 2010 at 10:26 AM, Carsten Haitzler ras...@rasterman.com wrote: On Mon, 25 Oct 2010 09:42:43 +0200 Cedric BAIL cedric.b...@free.fr said: the html docs should work offline too... just bring up index.html in a browser. I actually think that putting in each root header a link to the auto generated doc will help people that are looking at our API. We could also take into account the version when we do a release and point them to the right version of the doc online. This could be automatic. aaah that is indeed an issue yet undiscussed. we auto-generate docs for whatever trunk has. fine until we do evas2.0 or any api break.. as docs wont be wrong - they may just document new features not yet available in your versions of evas/edje/eina/whatever. so as of 1.0 we do NEED to make sure we clearly document as of when a feature is available (after 1.0 next round of features will be 1.1 - so any features and api's added need to be marked as added in 1.1). unless we want to generate new docs per minor version of evas? I have no strong opinion on that. The only draw back I see with online docs per minor version, is how search engine would handle them. If we do our job correctly, and have only one version online, people will know by reading the docs when it was added to the EFL. So I am a bit inclined to have only one auto build doc repository, but nothing really strong on that. that would be my preference too - we just need to document features added and what version they were added in specifically. anyway - still.. the question is being tossed back and forth. we have 2 sides. in .h or not. i ask this. read Eet.h - is that hard to use/read? would you prefer... Ecore.h for example? I tend to think that Eet.h is harder to read, but not only because of the doc, but because all functions are in it, eet_image*, eet_data* and so on. Having only one header per group of function help in that sense. As for Ecore.h, the only think I don't like is when pointer to callback function don't have a name that help understand what they do (I think I did fix all case in that header). eeek! i'm the opposite! i find eina a royal pita... :) (actually while i'm at it.. the tonne of eina headers... i'm not too fond of.. but we won't be changing this any time soon methinks). In fact, my preferred header at the moment are eina :-) Divided by functionalities, with some doc and tutorial where it make sense. i see we disagree there. i shall have to now beat you with a cow until you agree! :) /me beats cedric with la vache :) also one other thing. if we put API docs in the public .h - we can separately document internal info in the .c files - it's at least easier to handle doc-wise that trying to put different comment snippets within the same files in different doxygen sections (hell u'd want them in 2 separate documents at the end of the day). In eina, we did put the local part from the global part at the top of each .c files and they are already separated from the doxygen point of view. If we where considering adding documentation for the internal, it wouldn't be difficult. i just noticed.. some of eina's docs are in the public headers.. look at eina_log.h, eina_strbuf.h and eina_list.h for examples - others are not. this is a bit inconsistent even within eina. some things like the macros can only be documented in the .h as such... that leans me more towards the aaagh. for external API docs it smells like they all need to be in the public .h's as thats where structs are defined, macros and ... functions. so does someone have a solution for keeping the docs out of the public h's in the case of public structs and macros? :) if not - i suspect we'd just have to accept that we likely need to move them all there...? -- - Codito, ergo sum - I code, therefore I am -- The Rasterman (Carsten Haitzler)ras...@rasterman.com -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Mon, Oct 25, 2010 at 7:31 AM, Carsten Haitzler ras...@rasterman.com wrote: On Mon, 25 Oct 2010 11:15:42 +0200 Cedric BAIL cedric.b...@free.fr said: On Mon, Oct 25, 2010 at 10:26 AM, Carsten Haitzler ras...@rasterman.com wrote: On Mon, 25 Oct 2010 09:42:43 +0200 Cedric BAIL cedric.b...@free.fr said: the html docs should work offline too... just bring up index.html in a browser. I actually think that putting in each root header a link to the auto generated doc will help people that are looking at our API. We could also take into account the version when we do a release and point them to the right version of the doc online. This could be automatic. aaah that is indeed an issue yet undiscussed. we auto-generate docs for whatever trunk has. fine until we do evas2.0 or any api break.. as docs wont be wrong - they may just document new features not yet available in your versions of evas/edje/eina/whatever. so as of 1.0 we do NEED to make sure we clearly document as of when a feature is available (after 1.0 next round of features will be 1.1 - so any features and api's added need to be marked as added in 1.1). unless we want to generate new docs per minor version of evas? I have no strong opinion on that. The only draw back I see with online docs per minor version, is how search engine would handle them. If we do our job correctly, and have only one version online, people will know by reading the docs when it was added to the EFL. So I am a bit inclined to have only one auto build doc repository, but nothing really strong on that. that would be my preference too - we just need to document features added and what version they were added in specifically. anyway - still.. the question is being tossed back and forth. we have 2 sides. in .h or not. i ask this. read Eet.h - is that hard to use/read? would you prefer... Ecore.h for example? I tend to think that Eet.h is harder to read, but not only because of the doc, but because all functions are in it, eet_image*, eet_data* and so on. Having only one header per group of function help in that sense. As for Ecore.h, the only think I don't like is when pointer to callback function don't have a name that help understand what they do (I think I did fix all case in that header). eeek! i'm the opposite! i find eina a royal pita... :) (actually while i'm at it.. the tonne of eina headers... i'm not too fond of.. but we won't be changing this any time soon methinks). In fact, my preferred header at the moment are eina :-) Divided by functionalities, with some doc and tutorial where it make sense. i see we disagree there. i shall have to now beat you with a cow until you agree! :) /me beats cedric with la vache :) also one other thing. if we put API docs in the public .h - we can separately document internal info in the .c files - it's at least easier to handle doc-wise that trying to put different comment snippets within the same files in different doxygen sections (hell u'd want them in 2 separate documents at the end of the day). In eina, we did put the local part from the global part at the top of each .c files and they are already separated from the doxygen point of view. If we where considering adding documentation for the internal, it wouldn't be difficult. i just noticed.. some of eina's docs are in the public headers.. look at eina_log.h, eina_strbuf.h and eina_list.h for examples - others are not. this is a bit inconsistent even within eina. some things like the macros can only be documented in the .h as such... that leans me more towards the aaagh. for external API docs it smells like they all need to be in the public .h's as thats where structs are defined, macros and ... functions. so does someone have a solution for keeping the docs out of the public h's in the case of public structs and macros? :) if not - i suspect we'd just have to accept that we likely need to move them all there...? Yeah raster, we know you're big fan of anything that is long enough to fit into people's mind... like seen in your long functions and all. Just like Cedric, I'm much more found of Eina's docs, with split files. And I'd say our partial docs in .h with most of it in .c fits what Brian suggests as user. We tried to put some bootstrap and leave other stuff to .c. We could even move a bit more, like some tutorials to .h, but leave most of the functions in .c (unless inline functions that must stay there anyway). -- Gustavo Sverzut Barbieri http://profusion.mobi embedded systems -- MSN: barbi...@gmail.com Skype: gsbarbieri Mobile: +55 (19) 9225-2202 -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Mon, 25 Oct 2010, Gustavo Sverzut Barbieri wrote: On Mon, Oct 25, 2010 at 7:31 AM, Carsten Haitzler ras...@rasterman.com wrote: On Mon, 25 Oct 2010 11:15:42 +0200 Cedric BAIL cedric.b...@free.fr said: On Mon, Oct 25, 2010 at 10:26 AM, Carsten Haitzler ras...@rasterman.com wrote: On Mon, 25 Oct 2010 09:42:43 +0200 Cedric BAIL cedric.b...@free.fr said: the html docs should work offline too... just bring up index.html in a browser. I actually think that putting in each root header a link to the auto generated doc will help people that are looking at our API. We could also take into account the version when we do a release and point them to the right version of the doc online. This could be automatic. aaah that is indeed an issue yet undiscussed. we auto-generate docs for whatever trunk has. fine until we do evas2.0 or any api break.. as docs wont be wrong - they may just document new features not yet available in your versions of evas/edje/eina/whatever. so as of 1.0 we do NEED to make sure we clearly document as of when a feature is available (after 1.0 next round of features will be 1.1 - so any features and api's added need to be marked as added in 1.1). unless we want to generate new docs per minor version of evas? I have no strong opinion on that. The only draw back I see with online docs per minor version, is how search engine would handle them. If we do our job correctly, and have only one version online, people will know by reading the docs when it was added to the EFL. So I am a bit inclined to have only one auto build doc repository, but nothing really strong on that. that would be my preference too - we just need to document features added and what version they were added in specifically. anyway - still.. the question is being tossed back and forth. we have 2 sides. in .h or not. i ask this. read Eet.h - is that hard to use/read? would you prefer... Ecore.h for example? I tend to think that Eet.h is harder to read, but not only because of the doc, but because all functions are in it, eet_image*, eet_data* and so on. Having only one header per group of function help in that sense. As for Ecore.h, the only think I don't like is when pointer to callback function don't have a name that help understand what they do (I think I did fix all case in that header). eeek! i'm the opposite! i find eina a royal pita... :) (actually while i'm at it.. the tonne of eina headers... i'm not too fond of.. but we won't be changing this any time soon methinks). In fact, my preferred header at the moment are eina :-) Divided by functionalities, with some doc and tutorial where it make sense. i see we disagree there. i shall have to now beat you with a cow until you agree! :) /me beats cedric with la vache :) also one other thing. if we put API docs in the public .h - we can separately document internal info in the .c files - it's at least easier to handle doc-wise that trying to put different comment snippets within the same files in different doxygen sections (hell u'd want them in 2 separate documents at the end of the day). In eina, we did put the local part from the global part at the top of each .c files and they are already separated from the doxygen point of view. If we where considering adding documentation for the internal, it wouldn't be difficult. i just noticed.. some of eina's docs are in the public headers.. look at eina_log.h, eina_strbuf.h and eina_list.h for examples - others are not. this is a bit inconsistent even within eina. some things like the macros can only be documented in the .h as such... that leans me more towards the aaagh. for external API docs it smells like they all need to be in the public .h's as thats where structs are defined, macros and ... functions. so does someone have a solution for keeping the docs out of the public h's in the case of public structs and macros? :) if not - i suspect we'd just have to accept that we likely need to move them all there...? Yeah raster, we know you're big fan of anything that is long enough to fit into people's mind... like seen in your long functions and all. Just like Cedric, I'm much more found of Eina's docs, with split files. And I'd say our partial docs in .h with most of it in .c fits what Brian suggests as user. We tried to put some bootstrap and leave other stuff to .c. We could even move a bit more, like some tutorials to .h, but leave most of the functions in .c (unless inline functions that must stay there anyway). About tutorials, there are 2 solutions: 1) keeping them in the source code (like in eina) 2) put them in external file (tutorial_***.dox in the doc/ dir) I prefer the 1st solution: you have more chance to remember changing / updating the tutorial if it is in the source code than in an external file. Vincent -- Nokia and ATT present the
Re: [E-devel] efl documentation (for 1.0.0)
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. -- Cedric BAIL -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
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) -- Cedric BAIL -- Nokia and ATT 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 -- Gustavo Sverzut Barbieri http://profusion.mobi embedded systems -- MSN: barbi...@gmail.com Skype: gsbarbieri Mobile: +55 (19) 9225-2202 -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Fri, Oct 22, 2010 at 7:05 AM, Gustavo Sverzut Barbieri barbi...@profusion.mobi wrote: 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) -1 too. Header becomes much more difficult to read. Maybe user should be directed to the docs that are automatically generated... Lucas De Marchi -- Nokia and ATT 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
[E-devel] efl documentation (for 1.0.0)
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). -- - Codito, ergo sum - I code, therefore I am -- The Rasterman (Carsten Haitzler)ras...@rasterman.com -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Fri, 22 Oct 2010, Carsten Haitzler (The Rasterman) 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). I like having the doc in .h. Another related question: should we install doc ? For now, it is built only with 'make doc' and a tarball is built with html, latex and man doc. Vincent -- Nokia and ATT 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
Re: [E-devel] efl documentation (for 1.0.0)
On Fri, 22 Oct 2010 07:31:48 +0200 (CEST) Vincent Torri vto...@univ-evry.fr said: On Fri, 22 Oct 2010, Carsten Haitzler (The Rasterman) 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). I like having the doc in .h. Another related question: should we install doc ? For now, it is built only with 'make doc' and a tarball is built with html, latex and man doc. that is a good question. as such this may conflict with packagers and distros so for now i'd lean to no. especially if we put doxy comments in .h's -- - Codito, ergo sum - I code, therefore I am -- The Rasterman (Carsten Haitzler)ras...@rasterman.com -- Nokia and ATT 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
[E-devel] EFL documentation priorities
So I finished with the EFL introduction. I included (a slightly modified) stack diagram of the EFL libraries as designed by Rasterman. The document will soon appear in the E website as PDF (fop rendered!) and html too. The XML file will be imported in CVS so soon I am accepting patches for everything. Feel free to change the figures too. This document was what _I_ thought was missing from EFL documentation. I am thinking of updating the Edje book now. What do you all think? What do you feel that is missing from the Ejde book? What is obsolete? What Edje feature have you found that is not documented? What would you like to see in the Edje book? I have some additions from Brad Anderson which I am going to look through but anyone is free to say his opinion. Also if you feel that a new/other document has a higher priority than the Edje book and would be more useful to the EFL community, please say so! Kostis Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnkkid=120709bid=263057dat=121642 ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation priorities
Am Donnerstag, den 06.07.2006, 13:39 +0300 schrieb [EMAIL PROTECTED]: What do you feel that is missing from the Ejde book? More examples, perhaps task-based instead of feature-based, i.e. So if you want to have fade something out and something else into the same position, then do it like that... What would you like to see in the Edje book? Perhaps more on the interaction of Edje and Evas, i.e. how to work with swallowed elements, how to use color- and textclasses in a sane way, etc. Also if you feel that a new/other document has a higher priority than the Edje book and would be more useful to the EFL community, please say so! No! Edje is the most underrated UI library I know atm. - more documentation has a chance to fix that :) -- Regards, Michael 'Mickey' Lauer | FreeLancer | http://www.Vanille-Media.de Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnkkid=120709bid=263057dat=121642 ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
Re: [E-devel] EFL documentation priorities
Michael 'Mickey' Lauer wrote: Am Donnerstag, den 06.07.2006, 13:39 +0300 schrieb [EMAIL PROTECTED]: What do you feel that is missing from the Ejde book? More examples, perhaps task-based instead of feature-based, i.e. So if you want to have fade something out and something else into the same position, then do it like that... That would be more the domain of the EFL Cookbook then the Edje book. dan Using Tomcat but need to do more? Need to support web services, security? Get stuff done quickly with pre-integrated technology to make your job easier Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo http://sel.as-us.falkag.net/sel?cmd=lnkkid=120709bid=263057dat=121642 ___ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
