On Thu, 6 Nov 2014 22:14:35 +0100 Davide Andreoli <d...@gurumeditation.it> said:
> 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. thats why we share the core docs: (class description example) "this class handles setting timer events while the mainloop is running" (method example for freeze() on a timer) "this method freezes the timer - it will cease its timeout behavior until thawed, when it will continue where it left of from being frozen" those are language agnostic and we should. we MUST share them. we generate a per-lang specific page for everything eolian generates (as everything it generates will be available in all lannguages). eina is not eo based, and eo is a special case. everything else has to be via eo to be bound in other langs. right now i'm talking the api, event and class reference docs. in addition to these we need tutorial sections per language - "getting started". sample apps etc. it's much harder to share everything here - but it depends on the example and how much of the "wording" is language specific and how much is not. > > > 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 > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
