On Thu, 6 Nov 2014 09:25:12 +0100 Adrien Nader <adr...@notk.org> wrote:
> 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. That's what I did for Edje Lua, the Edje Lua documentation is a stub that mostly points to the C documentation for the C API that the Lua binds. -- 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
------------------------------------------------------------------------------
_______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
