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. 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. Best regards, -- 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 enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
