On Sun, Apr 5, 2015 at 6:28 PM, Carsten Haitzler <ras...@rasterman.com> wrote:
> On Sat, 4 Apr 2015 23:10:56 -0700 Jeff Grimshaw < > jeffrey.w.grims...@gmail.com> > said: > > > On Thu, Apr 2, 2015 at 7:22 PM, Carsten Haitzler <ras...@rasterman.com> > > wrote: > > > > > On Thu, 02 Apr 2015 16:20:38 +0200 Jonathan Aquilina < > > > jaquil...@eagleeyet.net> > > > said: > > > > > > > Not working in what sense? I would be up for looking into the issues > and > > > > getting things working with proper documentation through doxygen. > Since > > > > my programming know how that is needed for E is non existent. > > > > > > make doc (run a doxygen build run) across efl and elm take like > ~2-5mins > > > ... > > > thats about as long - even longer than compiling efl and elementary. > > > doxygen > > > has to do a FULL rebuild. it can't do a partial. that means turn-around > > > time > > > between you edited docs in src and seeing what they come out as is way > too > > > long. it should be no more than a few seconds. > > > > > > the docs somehow end up with mountains of the docs simply inaccessible. > > > they > > > are there but unlinked from master pages so navigating to them is > basically > > > impossible - and fixing it as above is a journey in such frustration > that > > > you > > > give up. > > > > > > This was me last year. I got about half way through trying to clean up > > eina docs > > before I gave up. Too much frustration and too many "Where did Doxygen > put > > the effing doc I just wrote?" moments. > > i totally get it. i've been there too. i threw my hands up in frustration > and > gave up. and i'm stubborn so i can only imagine how those less stubborn > might > react. I am also a very stubborn person. Once I decide that something needs fixing, I cannot let it go and feel compelled to work on it. I've just got to keep trying. My last commit was over a year ago but I haven't given up yet :-) > but proof is in the pudding. no one volunteers and actually gets things > done on docs. Agreed, applies especially to me :-) > as it stands right now it's simply not working. something about > how we do docs at the moment is causing this. devs don't bother because > getting > results from your doc efforts is like having someone pull your nails out. > non-devs just can't really contribute without going throug a whole patch > review > process. doxy docs imho are just ugly and fixing it all takes too long > (build > cycles as discussed). i'm up for trying something new. it can't be worse > than > what we have. :) Most of this dysfunction is because docs are not first class projects, they are just tacked on to the dev cycle and thus the first to go when time is short (and time is always short). The tooling is broken sure, but I don't think that's the primary reason why there are not many doc contribs. > > i dislike that doxygen just splats everything in a class (group) and all > > > api's > > > on a single page ... in whatever order it feels like. long ago in the > early > > > days of evas - back in 2001 or so i wrote a 200 page document on al of > > > evas. i > > > put 1 api call per page. it was neater and people actually liked the > docs. > > > never since has anyone liked the doxygen docs. > > > > > > the styling is ... bad. and hard to improve and customize further. > > > > > > > I will not defend Doxygen, because I hate it so, but the splatting and > > formatting > > can be fixed with different grouping and custom html/css. Many of the > > problems > > with the current docs are caused by Doxygen's group=page mentality and > its > > linking (or not) policy. > > but the time involved in fixing that grouping is insane... because > turn-round > time between "let me group like this" efforts here and there take multiple > minutes to see. even > 5 seconds is too much. > > > > no idea how to make doxygen properly link elm and efl docs - so when > you > > > have > > > evas_object_del() in elm docs - it points to the efl docs. it just is > > > totally > > > unlinked as the doc build is separate from efl. without a src tree > merge i > > > just > > > don't see this working. also as long as doc builds are part of src - > they > > > are > > > separate entites but efl is seen as efl + elementary by develoeprs and > they > > > complain bitterly if our docs are not unified as a single entity. in > fact > > > all > > > our existing efl docs pretty much assume ecore is separate to eina is > > > separate > > > to evas is separate to ecore_evas is separate to edje etc because that > is > > > just > > > how they always have been. it's time we stop that because people just > don't > > > like it. > > > > > > doxygen doesn't understand eo. it can't. it doesn't understand OO in > C. it > > > doesn't grok eo inheritance. we would have to fake generate pretend oo > > > docs for > > > C (some .h files with groups pretending to be classes, and hand-done > > > comments > > > and links on inheritance). it also doesn't understand events within > our eo > > > oo setup - that objects inherit events from parent classes. > > > > > > and frankly developers simply aren't writing docs. if we keep docs in > src > > > then > > > only devs can write them, and devs don't, so we will NEVER have docs > .. by > > > definition. i want to split docs out from the src in a way that means > we > > > don't > > > have long build times. so dedicated tech writers/documentation people > can > > > easily work on them. it won't be hard to make tools to import markdown > > > templates from the .eo files and thus add new classes, events, methods > as > > > they > > > appear (with empty docs), then to be filled in with fast feedback. > > > > > > > > Yep! :-) > > > > Docs should have their own tree, not mixed in with the source code. Docs > > should be a first-class project and be managed that way. Devs don't > write > > (mostly) and writers don't dev (mostly), so just ack that fact and > > create a space where the doc folks can do their work and not get in the > way. > > that is the direction i want to try. it can't be worse than what we have. > :) > > > I've been working (slowly) on converting things over to Docbook on my > > local. When > > I have something that works I will make it available on git so we have > > something > > to talk about. > > i actually wanted to look at docboook - so i quickly modded my doxyfile to > make > docbook docs... and doxygen refused to generate them. i spend maybe 30 mins > trying to get it to do it (waiting multiple minutes between tries)... i > gave > up. :) i wanted to see what our docs look like in docbook and see if we can > leverage that to move on from doxy. but i gave up. :) I tried that too and gave up. I didn't try very hard since I hate Doxygen :-P > i was "not so enthused" > by docbook in principle due to it being xml... (biased) :). I'm not a big fan of XML either and my first reaction to Docbook was a big WTF. Why are all these projects using it? Why should I bother with this arcane POS? I am still answering these questions for myself, but it has been shown to work for large complex projects and I want to know why and how. > at this point i'm > kind of convinced the path is to set up a new wiki, hand-fill it with some > initial content (copied over + edited/improved from our doxy docs), in > order to > get a handle on what the docs SHOULD look like (format/style/arrangement). > mess > with that until everyone is happy, then look at a larger migration of docs > as > well as auto-generating our new .eo world doc hierarchy. the first step of > course is new wiki coming up and getting current www.e.org content there > and to > begin to lay out some sample base for efl (and e and others) docs. wiki > first. > content next. then bring up live, then docs. :) > I think we're on the same page, or at least adjacent pages. Both our approaches can be fruitful and useful and may even complement each other. > > I chose Docbook because it's a standard and other large projects use it, > but > > if markdown is chosen for doc source, so be it. > > sure - understandable. > > > -- Jeff Grimshaw > > > ------------------------------------------------------------------------------ > > Dive into the World of Parallel Programming The Go Parallel Website, > sponsored > > by Intel and developed in partnership with Slashdot Media, is your hub > for all > > things parallel software development, from weekly thought leadership > blogs to > > news, videos, case studies, tutorials and more. Take a look and join the > > conversation now. http://goparallel.sourceforge.net/ > > _______________________________________________ > > 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 > > -- -- Jeff Grimshaw ------------------------------------------------------------------------------ BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT Develop your own process in accordance with the BPMN 2 standard Learn Process modeling best practices with Bonita BPM through live exercises http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual- event?utm_ source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
