Suggestion: Pull comments about philosophy / design of the library into one place in the documentation
haikusw opened this issue · 4 comments
commented on a couple of places where I ran into useful commentary that would like to be hoisted into the documentation but thought I'd put together a ticket to make it easier to track:
This comment here about what belongs in this library vs what should be layered over it by folks using this library:
#97 (comment)
I added the other bit I ran across to that thread (though it's a bit older so some no longer relevant):
#97 (comment))
@haikusw We've also added a doc about the library's general design here: https://pointfreeco.github.io/swift-parsing/main/documentation/parsing/design
Does this address the issue? Or do you think anything is still missing?
Sounds promising! I'll take a look soon and update this as appropriate.
@haikusw Thanks!
This is some very nice documentation.
I feel like the comment here #97 (comment) was a lot more specific and contained more concrete guidance for people writing parsers or thinking about making contributions to the library.
The second comment: #97 (comment))
seems like guidance for those considering contributing to this library (the first of these two comments applies both to contributing to this library and extending the library, seems like?).
Perhaps there wants to be sections in the documentation for "Contributing to this library" and "How to extend this Parsing library in your own layer built on top of it." Perhaps a couple of sentences about when someone should extend versus when they should offer something as a contribution? That seems to be what these two comments you made in the forums were about. I don't really see that spelled out as such.
This was just a suggestion because those two referenced comments seemed very detailed and helpful.