On Fri, 20 Jun 2014 11:17:49 +0100 Tom Hacohen <tom.haco...@samsung.com> said:
> On 20/06/14 00:11, Carsten Haitzler (The Rasterman) wrote: > > On Thu, 19 Jun 2014 15:17:28 +0100 Tom Hacohen <tom.haco...@samsung.com> > > said: > > > >> On 19/06/14 15:01, Carsten Haitzler (The Rasterman) wrote: > >>> On Thu, 19 Jun 2014 10:32:45 -0300 Felipe Magno de Almeida > >>> <felipe.m.alme...@gmail.com> said: > >>> > >>>> On Thu, Jun 19, 2014 at 10:18 AM, Daniel Kolesa <quake...@gmail.com> > >>>> wrote: > >>>>> 2014-06-19 14:02 GMT+01:00 Tom Hacohen <tom.haco...@samsung.com>: > >>>>> > >>>>>> Hey, > >>>> > >>>> Hello Tom, > >>>> > >>>> [snip] > >>>> > >>>>>> We are working on the Eo EFL API, making it clean, consistent, and > >>>>>> predictable. This work covers sharing similar interfaces among similar > >>>>>> classes all over the EFL, adding Eo API to things that are not covered > >>>>>> by Eo at the moment and should be, and probably in the future also > >>>>>> fixing some broken API we might have lingering around. > >>>> > >>>> [snip] > >>>> > >>>>> It's pretty clear that we need something like this. But I fear that > >>>>> having lots of "global" efl_ prefixed funcs will lead to interface > >>>>> creep, not something we necessarily need; also, it means we'll have to > >>>>> split these into many different interfaces - we will want to categorize > >>>>> these somehow, instead of shoving everything into one. > >>>> > >>>> I don't think they are the same function. To say that they set a file > >>>> is way too simple. Each function sets for a different purpose and that > >>>> must be documented. They are different functions and in a OO (I don't > >>>> even like OO, but just to use as an example that not even OO-people > >>>> would do this) these functions wouldn't be related at all, they > >>>> wouldn't override each other or anything. > >>> > >>> in this case, they should conceptually do the same job. take the object > >>> and point it at a file to deal with. it may be for reading. it may be for > >>> writing. how it decodes etc. may vary, but the primary obvious and > >>> expected behavior should be the same, otherwise don't use the api. > >>> > >>> but indeed we do need a way to document overridden methods if they do > >>> something differently enough worth documenting. > >>> > >>> we have another big problem which is documentation across multiple > >>> languages too - where the docs for a function (method) or property (maybe > >>> 2 funcs) needs to be able to differentiate between core "language > >>> agnostic" docs and "language specific paragraphs". it's a problem that, > >>> as best i know of, to date, has never been solved in any doc tool i know > >>> of. > >> > >> Yep. We'd need to implement our own doc tool anyway (and gen doxygen > >> docs that can be generated?) because of the C OOP, so we can probably > >> just add annotation about Python only sections, C only sections, and etc. > > > > i'm actually mulling removing docs entirely from eo files - eo files just > > generate empty doc bundles per class/func - these bundles (format not > > relevant) just describe the class. the rest is an interactive website > > and/or remote api (json, xml plain text over http) for people to query, > > list, search, edit and discuss. like a wiki people can edit the core doc > > section (starts as empty), then can optionally fill in other sections for > > other langs (imagine each extra lang section is a separate text file and > > edit field - you can filter per lang you like/use/know/are interested in so > > you dont have to get all) so when not editing the filter will hide lang > > info that is not relevant to you (only doing lua? why so you care what the > > c specific docs say? they mean nothing to you). even better if like > > stackoverflow or reddit you can have comments/q&a's per page (the general > > class overview page or per method/property page, other > > tutorial/guide/overview pages etc.). people can ask q's, get answers and > > people vote them up and down... make documentation a community involved > > effort... "crowdsource it". > > Yes, we talked about it. I also think it's much cleaner and easier > solution. A problem that comes to mind is the decoupling of the docs > from the code, and revisions. > > What you are referring to is done with php (quite ugly tbh). All of > their docs are actually some docs followed by discussions. oh i didn't know. they do have user comments. and you can edit it. yes - we want this - maybe a bit less cluttered, but with some extra bits like a common section plus a per-language set of sections. maybe what php uses to do docs we should use? or modify/adapt? i don't know. this is a debate worth having - and some research too. -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ HPCC Systems Open Source Big Data Platform from LexisNexis Risk Solutions Find What Matters Most in Your Big Data with HPCC Systems Open Source. Fast. Scalable. Simple. Ideal for Dirty Data. Leverages Graph Analysis for Fast Processing & Easy Data Exploration http://p.sf.net/sfu/hpccsystems _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
