Refactor damldocs -- turn types into newtypes #1883
Conversation
ghost
requested review from
| , indent 2 (fieldTable cd_fields) | ||
| ] | ||
| [ prefix "* " $ asCode (unTypename cd_name) | ||
| , maybe " " (flip T.snoc '\n' . indent 2 . unDocText) cd_descr |
There was a problem hiding this comment.
👍 indentation added. Makes sense.
| [ " : " | ||
| , maybe "" ((<> " => ") . type2rst) fct_context | ||
| , maybe "" ((<> "\n\n") . type2rst) fct_type | ||
| -- FIXME: when would a function not have a type? |
There was a problem hiding this comment.
Functions could have no (explicitly-stated) type but a doc comment.
(as long as we still use the parser AST... the type checker will give every function a type)
There was a problem hiding this comment.
Ah, makes sense! We should probably switch to typechecker AST like you were saying.
There was a problem hiding this comment.
Maybe worth replacing the FIXMEs by explanations?
| , prefix " - " $ type2rst fd_type | ||
| , prefix " - " $ maybe " " (markdownToRst . T.unwords . T.lines) fd_descr ] | ||
| , prefix " - " $ maybe " " (docTextToRst . DocText . T.unwords . T.lines . unDocText) fd_descr ] -- FIXME: this makes no sense |
There was a problem hiding this comment.
That construction unwords . lines might seem funny... the idea was to ensure the documentation text is a single line. Otherwise we need to indent it correctly, which is a bit fiddly.
However, it might be better to do that. As a principle, we should retain the line breaks in doc.text over multiple lines. More important for doc.s on modules and top-level declarations, though.
There was a problem hiding this comment.
Yeah, makes sense. I was thinking of introducing an intermediate representation in Render.RST (and Render.Markdown which has the same problems) to make it easier to indent things correctly. Some kind of "rendered doc" IR that can be converted to Rst or Markdown easily. Because right now there's a lot of duplication between the output modes of damldoc, and the same issues cropping up over and over again.
Renamed
Markdowntype toDocText(to avoid confusion with theMarkdownconstructor in Render.hs). Use newtypes forDocText,Fieldname,TypenameandModulename, instead of representing all these different types of text as type aliases ofText. Refactored some functions and deduplicated some code as well. The goal was not to change the output, only the code.But I did find one bug in the process, which I fixed: module descriptions were being returned as Rst without conversion from Markdown first.