[libcxx-commits] [PATCH] D105082: [libcxx][NFC] removes header synopses

[Christopher Di Bella via Phabricator via libcxx-commits]

cjdb added a comment.

In D105082#2847148 <https://reviews.llvm.org/D105082#2847148>, @ldionne wrote:

> The purpose of those synopses is not to document what the Standard says, but instead to document what the state of our library implementation is. As such, they are often useful to figure out what has been implemented and what's missing from the library. They are especially useful when trying to figure out what parts of a partially implemented paper are missing (for the numerous papers where we only have "In Progress" in our tables). I also find that they help when reviewing patches, since they act as a summary of what the patch is doing (at least in most cases where we're implementing something new).

I'm not really seeing how they document the state of the library implementation. If one wants to know if something is implemented, we can just grep for it? If this info is genuinely valuable (and I'm seeing your point about "In Progress"), then I think it would be worth us moving the synopses out of the code and into status documents. I think that would be immensely more useful than having them in the same document, because they're more accessible (we can link "In Progress" statuses to specific webpages), and because it's not duplicating the interface in the code.

> It is true they are a maintenance burden, but how much time do you *actually* spend updating those? It's really not a major source of wasted time in my experience. The main problem IMO is that we don't have a way to remind ourselves to update the synopses. If we were on GitHub, for example, we'd have a checklist reminder on pull requests that would contain a few things like "did you update the modulemap?" and "did you update the synopses?". The synopses would be more up-to-date and I don't think we'd have that conversation.



> For all those reasons, I think we should keep synopses around, but I'm open to discussion.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D105082/new/

https://reviews.llvm.org/D105082