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 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. > 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. 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 chose Docbook because it's a standard and other large projects use it, but if markdown is chosen for doc source, so be it. -- 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
