Hello. On 24/10/16 05:15, Jean-Philippe André wrote: > 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).
Yeah, I know. You brought this very valid point up once before and I did not forget about it. It leads to stalling the documentation effort thought. When you brouht it up I stopped the effort and thought I will wait until 1.18 is out and the current EO files are final. Didn't happen and we are still off by a good margin to come to this state. I feel I might even better keep going here and spent some later obsolete time on eo files instead of not working on it at all. :) None the less your refresher is appreciated and I will try to keep the various areas in mind and focus on others. 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? Well, with your effort to remove many of the unnecessary installed EO files this makes sense. So far it did not really make much of a difference thought and allowed for quicker testing (no need to make sure all old EO files are removed and installing the latest before running docgen) > This unfortunately fails with "bad argument #2 to > 'eolian_function_scope_get' (cannot convert 'nil' to 'unsigned int')". Hmm, I will see if I can reproduce this. Maybe Daniel does know more. > 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 :) I expected that someone will bring this up. :) What is the real downside of doing it thought? It will cost you 2 seconds to write the doc for the return. Initially it will look obvious and it might stay this way. It could also happen that some special conditions need to be added. With the switch to a wiki based doc system we also want to lower the barrier for users to contribute (on the wiki side and not in the repo directly). Giving them the basic doc at hand to edit and extent is important in my opinion. Even obvious parameters like len look a lot better being described as "Length of the appended string" in the docs. A last, very selfish, argument is that giving out exceptions for some cases makes it hard to track if we have all the needed other bits documented (tooling can not make the decision here if somethign is so obvious that it does not need a doc. That is even a different taste between people. :)) regards Stefan Schmidt ------------------------------------------------------------------------------ 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
