package reason

* Provides a simple interface to the most common parsing entrypoints required * by editor/IDE toolchains, preprocessors, and pretty printers. * * The form of this entrypoint includes more than what the standard OCaml * toolchain (oprof/ocamldoc) expects, but is still compatible. * * implementation_with_comments and interface_with_comments includes * additional information (about comments) suitable for building pretty * printers, editor, IDE and VCS integration. * * The comments include the full text of the comment (typically in between the * "(*" and the "*)", as well as location information for that comment. * * WARNING: The "end" location is one greater than the actual final position! * (for both associatedTextLoc and commentLoc). * * Currently, the location information for comments is of the form: * * (associatedTextLoc) * * But we should quickly change it to be of the form: * * (associatedTextLoc, commentLoc) * * Where the commentLoc is the actual original location of the comment, * and the associatedTextLoc records the location in the file that the * comment is attached to. If associatedTextLoc and commentLoc are the * same, then the comment is "free floating" in that it only attaches to itself. * The Reason pretty printer will try its best to interleave those comments * in the containing list etc. But if associatedTextLoc expands beyond * the commentLoc it means the comment and the AST that is captured by * the associatedTextLoc are related - where "related" is something * this reason_toolchain decides (but in short it handles "end of line * comments"). Various pretty printers can decide how to preserve this * relatedness. Ideally, it would preserve end of line comments, but in the * short term, it might merely use that relatedness to correctly attach * end of line comments to the "top" of the AST node. * * let lst = * * ; (* Comment *) * ----commentLoc----- * ---associatedTextLoc---- * * * Ideally that would be formatted as: * * let lst = * * ; (* Comment *) * * Or: * * let lst = ; (* Comment *) * * * But a shorter term solution would use that associatedTextLoc to at least * correctly attach the comment to the correct node, even if not "end of line". * * (* Comment *) * let lst = ;