Hi Stefan, On 22 October 2016 at 07:43, Stefan Schmidt <[email protected]> wrote:
> Hello. > > TL;DR: If you are committing new eo files I expect them to have full > docs from now one. Also help with the ones you are currently working on. > > Longer version: > If you look at the commit log you can see that I started another crusade > on getting our doc coverage for eo files. > > Right now we have the following stats for our documentation efforts: > > === CLASS SECTION: 269 out of 864 (31%) === > > Classes: 255 (documented: 93 or 36%) > Interfaces: 57 (documented: 22 or 39%) > Mixins: 28 (documented: 28 or 100%) > Events: 524 (documented: 126 or 24%) > > === FUNCTION SECTION: 6440 out of 7790 (83%) === > > Methods: 1016 (documented: 936 or 92%) > Method params: 1667 (documented: 1401 or 84%) > Method returns: 493 (documented: 310 or 63%) > Getters: 1059 (documented: 970 or 92%) > Getter returns: 175 (documented: 105 or 60%) > Getter keys: 120 (documented: 89 or 74%) > Getter values: 1197 (documented: 924 or 77%) > Setters: 845 (documented: 779 or 92%) > Setter returns: 69 (documented: 43 or 62%) > Setter keys: 57 (documented: 49 or 86%) > Setter values: 1092 (documented: 834 or 76%) > > === TYPE SECTION: 1240 out of 1775 (70%) === > > Aliases: 84 (documented: 9 or 11%) > Structs: 82 (documented: 57 or 70%) > Struct fields: 191 (documented: 156 or 82%) > Enums: 170 (documented: 154 or 91%) > Enum fields: 1248 (documented: 864 or 69%) > > === VARIABLE SECTION: 56 out of 56 (100%) === > > Constants: 0 (documented: 0 or 100%) > Globals: 56 (documented: 56 or 100%) > > === TOTAL: 8005 out of 10485 (76%) === > > Which means we have 2480 undocumented items. > > I'm willing to work on this and I actually doing it already but if your > working area covers some eo files please make sure that you document all > bits in there. Some might look silly on a first glace (enums fields, > etc) but getting this to a 100% coverage, and keeping it, really helps > the doc efforts. We are using these to generate our documentation and > after some time for setup and migration of the older doxygen docs we > will switch to them. An example how they look like is here (design and > layout is up for suggestions but need to stay aligned with our www theme > to have a consistent look): > https://devs.enlightenment.org/~stefan/dokuwiki/doku.php? > id=docs:efl:auto:reference > > To keep track on the progress you can use: > src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -src/lib/ > > To get an output of what items are still need docs use the verbose flag: > src/bin/elua/elua src/scripts/elua/apps/gendoc.lua -v src/lib/ Thanks for sharing this. One thing to note though is that a massive number of undocumented APIs are not meant to be part of our EO set of APIs. Either because they are not well (re)designed (eg. Ecore_Audio) or because they are meant to be internals (eg. Ector). I'll try to remove some of the EO files from the install, step by step. I assume gendoc.lua should be run against <eflinstall>/share/eolian/include rather than the internal lib folder? This unfortunately fails with "bad argument #2 to 'eolian_function_scope_get' (cannot convert 'nil' to 'unsigned int')". Also, I would argue that quite often an obvious parameter, getter return, etc... doesn't need to be documented, so the goal shouldn't be 100% coverage :) -- Jean-Philippe André ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, SlashDot.org! http://sdm.link/slashdot _______________________________________________ enlightenment-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
