straight-shoota
commented
4 years ago Building on that idea, I'd like to propose refactoring the docs generator, to more effectively separate it into two stages:
- extracting a documentation model from the parsed program
- processing that data into display format (HTML)
The interface between both stages would be a structured format which can easily be serialized to JSON and would also serve as an external interface which can be used for customized doc generators and other purposes.
We've discussed about potentially removing the HTML-generation from the compiler entirely. This proposal doesn't go this far, but it would be a preparation for that. But it's a good improvement anyway to refactor and separate concerns.
jkthorne
crysbot
4746 added JSON serialization for Crystal API components like types, methods, constants etc.
The implementation uses custom
#to_jsonmethods to extract the data from the compiler models.However, it would be great if there was a way to also deserialize the JSON data into Crystal models. This is necessary for external doc generators to hook in. It also offers possibility for other uses of the generated API model.
This doesn't necessarily need to be part of the stdlib, but given that the serialization part is required for the compiler anyway, I figure it would make sense to also add the deserialization so both can be kept in sync.
The best way to do this would be to implement simple data model types with JSON serialization. The compiler types would just create such a model instead of serializing directly with custom
#to_jsonmethods. A rough draft of the API model can be seen here: https://gist.github.com/straight-shoota/d6b783dd4c973712aa6a2183153fd391