On Thu, 23 Jun 2016 15:34:50 +0200 Stefan Schmidt <ste...@osg.samsung.com> said:
> Hello. > > As many of you know already Daniel was working on extending eolian and > writing a elua script to generate dokuwiki pages from our EO docs. > > We are now on a level where we should ask for some feedback for what we > have done so far. Raster already started with this today on IRC so I > thought it might be worthwhile to bring it to the list. > > First of all here is what we have right now. Its a toy setup for myself > but it is supposed to get integrated into the main efl dokuwiki setup. > > https://devs.enlightenment.org/~stefan/dokuwiki/doku.php?id=efl:reference > > It is manually updated and I just did a fresh run today. Feel free to > click around and get used to it. CSS and design is just copied over from > our main dokuwiki theme and might need tweaking here and there. > > The feedback we got so far for the layout: > o The graph might not be needed all times as the text above already > shows the inheritance. Having the graph is nice though for others. Maybe > have it as fold in somehow to people can let it show easily if they are > interested. > o Do we need to EO signature? > o The method link could already show params and return values > o Separate class functions form normal ones > > Let more feedback come. > > The plan would be to get this doc system into the main wiki and filled > up with what we have after the 1.18 release is out. Form that point on > we can also have more people editing docs in the wiki itself while > people with commit access can work on covering all doc elements in the > EO files. > > Content wise we still have a lot to cover. Feel free to chime in here. I > started on some EO files but stopped for a while to let all the work on > interfaces settle first before we try to get it all covered. > One one major things we need to think about is that our docs should read > coherent. Different people write them but the reader should still have > the feeling that concepts are described in one part in the same way they > are in another. Simple example would be how we describe a pointer to > some private data for the function. This should be the same over all docs. > > I'm neither a technical writer nor native english speaker so I really > seek suggestions here. I'm willing to to the manual labour here to get > this changed once we have found things that are inconsistent and needs > change over all EO files. Kind of a documentation style guide. I will > try to start this here when I come back to the docs but wanted to > mention it in case people have some ideas. > > regards > Stefan Schmidt events - i think maybe like methods a table might be nice. also i think having expandable/foldable sections flatenning out methods, properties and events inherited from parent classes. it really saves clicking on every parent class to find out all the things this class can do. also with methods explicitly mark which ones are implemented (overridden) by this class somehow. the property has a get,set - maybe another 2 columns in the table with a checkmark in the get and set columns... also type of the property and if any keys used etc. etc. with the property. with properties and methods we have no parameters and also no typing info either. that'd be REALLY good to have typing in the main class page, not just the pages linked to for the details. also for events we have no info on the event info type used - the struct etc. etc. - no links there to anything and no details in the event list. > PS: for stats lovers here is what the docgen script gives us about our > current doc coverage: (Plenty of opportunities to help :)) > > stefan@workmachine efl (master) $ src/bin/elua/elua > src/scripts/elua/apps/docgen/gendoc.lua src/lib/ > === CLASS SECTION === > > Classes: 239 (documented: 70 or 29%) > Interfaces: 53 (documented: 17 or 32%) > Mixins: 18 (documented: 6 or 33%) > Events: 525 (documented: 107 or 20%) > > === FUNCTION SECTION === > > Methods: 1040 (documented: 951 or 91%) > Method params: 1715 (documented: 1426 or 83%) > Method returns: 495 (documented: 308 or 62%) > Getters: 971 (documented: 875 or 90%) > Getter returns: 151 (documented: 82 or 54%) > Getter keys: 66 (documented: 33 or 50%) > Getter values: 1112 (documented: 833 or 75%) > Setters: 771 (documented: 696 or 90%) > Setter returns: 47 (documented: 22 or 47%) > Setter keys: 26 (documented: 18 or 69%) > Setter values: 1024 (documented: 773 or 75%) > > === TYPE SECTION === > > Aliases: 87 (documented: 9 or 10%) > Structs: 77 (documented: 36 or 47%) > Struct fields: 166 (documented: 82 or 49%) > Enums: 159 (documented: 133 or 84%) > Enum fields: 1104 (documented: 780 or 71%) > > === VARIABLE SECTION === > > Constants: 0 (documented: 0 or 100%) > Globals: 0 (documented: 0 or 100%) > > > ------------------------------------------------------------------------------ > Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San > Francisco, CA to explore cutting-edge tech and listen to tech luminaries > present their vision of the future. This family event has something for > everyone, including kids. Get more information and register today. > http://sdm.link/attshape > _______________________________________________ > 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 ------------------------------------------------------------------------------ Attend Shape: An AT&T Tech Expo July 15-16. Meet us at AT&T Park in San Francisco, CA to explore cutting-edge tech and listen to tech luminaries present their vision of the future. This family event has something for everyone, including kids. Get more information and register today. http://sdm.link/attshape _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
