Hi Stephen, Stephen Gregoratto wrote on Mon, Nov 26, 2018 at 09:24:25PM +1100:
> Thanks for your response Ingo. I think I'll start with the missing > functions and go through them by order of length. Not saying "by order of length" is impossible, but keep in mind that * There are few section 3 manual pages documenting only a single function, especially in bloaty libraries like libcrypto/libssl, it is usually better to document very closely related functions together on one page. (Rule of thumb: avoid text duplication, but don't make pages too long and complicated.) * Going by length implies that you will have to learn about a new sub-library for almost every function you tackle. * Going by length implies that you will be sending a mix of diffs for functions of vastly different importance; it may be harder to get reviews for functions of lower importance and to get those committed. So the criterion "by length" will surely make things harder for you. Not saying the criterion is impossible to use, just making sure you know it has some serious downsides for you. > I'll try and peruse > through the ports and check for any examples. Be aware that functions exist that are notoriously misused, and code in ports is of widely varying quality. Large parts of the ports tree contain code that is way below OpenBSD quality standards, so you will learn much less from looking at ports code than from looking at base system code, unless you know which ports are of unusually high code quality. > Speaking of functions: I'm trying to generate a list of each function, Not saying "don't do that" - but be aware that the reason why nobody did that yet (not even when giving a public talk that included statements about "future directions") is that it is not really needed in the current situation to make progress. Such a list becomes useful when we get very close to the goal of having everything documented. That is years in the future at best. A list containing hundreds of functions doesn't seem all that useful to me. > the source file it's defined in and the corresponding line number, > similar to the format of `grep -n`. Is there a way to force ctags to > output in some tabular format that can be AWK'd? The -x option isn't > cutting it for me. I have no idea, i never used ctags(1), nor any similar tool for that matter. I never saw a use for it. I you want to use it, figure it out. :) There is no need to try and refute the points made in this posting, and you can proceed as described here if you really want to. I'm merely trying to make sure that you are not making the project harder for yourself without even being aware that that's what you are doing. After all, you asked for advice on how to proceed and neither "producing a complete list of missing functions" nor "mastering automated tools for static source code analysis" was anyway near my list of potential obstactles that might have to be overcome. ;-) Yours, Ingo
