Hello. On 24/10/16 11:27, Jean-Philippe André wrote: > Hey Stefan, > > On 24 October 2016 at 17:27, Stefan Schmidt <ste...@osg.samsung.com> wrote: >> >> [...] >>> 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. :)) >> <https://lists.sourceforge.net/lists/listinfo/enlightenment-devel> >> > > In fact, it's a matter of choice. I agree with you as well (yes, I'm > contradicting myself). > > Either the documentation generator duplicates the string or a human does it. > I'm fine with either. Human-written doc can potentially look better but it > means we'll have a lot of empty spots until we fill them in.
Sure, but we are not to bad. With 76% off all items covered. That is even for files that will not be part of our public API. When we focus on the eo files meant as public API (removing non public eo files from install and running the generator on the installed files only) we wil have a reduced total number and, maybe, a higher documented level. In any case I'm willing to bring this forward and will continue to work on the empty spots. > As for stalling the documentation work, I believe the more you will expose > those stats and doc pages, the more incentive we will have to remove > excessive eo files and document those that need to be. I hope so to :) Maybe I should add them to the QA report each week. (and rename it to Stefan's weekly statistic newsletter. ;)) 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 enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
