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. Though I wonder if there's a way to put that outside of the .eo, and into .eo.doc overrides per language that add more info and are contained elsewhere. Reason for that being, is that it's really not .eo related. -- Tom. ------------------------------------------------------------------------------ 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
