Can’t agree more. The first kind of doc is useful from time to time to check the correct argument of a function. The second one is about the big picture and the overall architecture. And sadly this is what is missing with every codebase I’ve worked on. In my project on the contrary, this is something I try to document.