2014-11-06 9:25 GMT+01:00 Adrien Nader <adr...@notk.org>: > On Thu, Nov 06, 2014, Carsten Haitzler wrote: > > i thought i'd start this here for a wide audience. > > > > documentation for efl. it's rather horrible. and yesterday it dawned on > me... > > it has license problems too. > > > > 1. license problems: > > > > the documentation in many parts is lgpl - and that means copying any > code from > > code snippets or examples in the docs makes the app you copy it into > lgpl. that > > is BAD. enforcing the license even though with lgpl we intend the library > > boundary to be the library itself. we can add exceptions, but splitting > docs > > out might actually be best. reality is that no one is ever going to sue > over > > this and it's safe as it's not intended to be a problem, but > strictly/legally > > it is. if someone has a legal department that really dots their i's and > crosses > > their t's... they would spot this. > > A related discussion: > https://lists.debian.org/debian-legal/2008/06/msg00012.html > > Fortunately, examples are most often separate files with short > modification histories and only a few authors total. Relicensing > shouldn't be a huge pain of tracking down everyone. > > Also, since they're separate files and works, they might not even be > LGPL or anything but full-copyright. > > > 2. our docs are a mess. a lot are not linked to and undiscoverable. they > have > > typos, missing docs - often are sparse and with little or nothing in the > way of > > binding things together. they are at best a very slim reference set for > apis > > with little besides that. some references are good, but most are also > very > > thin. keeping docs totally in the hands of core devs (always in the > source > > tree - src commit access needed) simply is *NOT WORKING*. devs work on > code. we > > just are not doing docs. we should do them, but reality is we are not > and have > > little incentive to do it. core devs are busy enough as-is. > > Definitely agreed. Making the glue with doxygen between the various API > pages is fine once you've done enough doxygen but wiki or something > similar might be better for glue (and intros and tutorials and ...). > > For the tutorials and the likes, better to wait a bit before starting to > work on these. > > > 3. eo brings the added problem of needing docs to cover multiple > languages > > from a single source. C, C++, Lua, JS, Python... it's a unique problem > that > > using doxygen is never going to solve. we need a solution. i haven't > found > > another solution and to be honest ours will be custom due to eo/eolian > anwyay. > > It's not terribly pretty but having no documentation in the bindings is > acceptable imho. Put a link at the top of each of their API ref to the > documentation for the C code, and stop there. The bindings are so close > to 1:1 that they're easy to understand. >
I disagree here, bindings need proper documentation, with proper tutorial/examples written in that language. Looking at the c docs is good only for people that know the c language, for example the average python developer don't know nothing about c and cannot understand examples or docs written in c. Trust me, I tell this by experience. In fact we put lots of effort on the python-efl documentation ( https://build.enlightenment.org/job/base_pyefl_build/lastSuccessfulBuild/artifact/build/sphinx/html/index.html) and still the users fail to found the info they need. For python also we do not provide bindings for 100% of the C api, lots of stuff are left off because they are too much low-level or because python provide the same functionality natively. Eina is a good example here: python-efl do not provide Eina bindings because python yet provide all the needed datatypes, and thus the python user don't need/want to learn eina just to understand the docs, eina must be left off to the python developer eyes....that means shared docs are not an option IMO. > > > 4. people ask questions on efl all the time and we answer in email, irc > etc. .. > > and this information is not captured. it's lost. that's because there is > no > > "forum" for asking such q's. we should closely tie such forums and q&a to > > documentation. this would massively improve the value of docs. > > > > 5. the theory of keeping docs with the code is just not working. it > doesn't > > encourage them to be good. it just isn't working - plain and simple. > it's time > > to re-evaluate that. > > Again, agreed. > > > [...] > > And the rest sounds good but that's a large proposal so needs time to > check and think about it. > > -- > Adrien Nader > > > ------------------------------------------------------------------------------ > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
