yard
yard copied to clipboard
lsegal
Markup agnostic extra files
Description
Rewrite how comments are handled in textual files (extra objects). Prefer markup-agnosticism over sticking to HTML comments. Do not remove comment tags, as they are bound to specific markup, and hidden from user's eye anyway. As an effect, more types of comments are now supported, including ones from AsciiDoc and Textile. Fixes #1192.
This is a somewhat breaking change (see).
Possible improvements
If required, I can restore previous behaviour changed in dc5788a, making this change a non-breaking one. Well, at least in terms of how it was formally specified in specs.
It's just a matter of adding following lines to the altered case construct:
when /^\s*$/
cut_index_end = index
break
See also
- discussion in Yard's mailing list
Completed Tasks
- [x] I have read the Contributing Guide.
- [x] The pull request is complete (implemented / written).
- [x] Git commits have been cleaned up (squash WIP / revert commits).
- [x] I wrote tests and ran
bundle exec rakelocally (if code is attached to PR).
Coverage increased (+0.004%) to 93.443% when pulling bcfb36ceb5c2112fa3eaef350b3dd2fda8a1688e on skalee:markup-agnostic-extra-files into 89ea314850ca6296216c368a777d91767d521146 on lsegal:main.
There are definitely concerns about breaking changes here. I realize that you show a non-breaking option, but I'm not 100% sure that dc5788a5c386997d72625c0579f4df2b17adc8ed is really the only breaking change. It seems to me that all of these parser changes would break examples where, for example, a user was attempting to render an HTML document, i.e.:
<!--
# a comment
-->
<html>
<head>
...
This would potentially incorrectly render the comment in the document, depending on its contents.
This is quite an edge case, I realize, but it should be clear that this is technically a breaking change.
I actually think that the "2 newlines" option is actually the least breaking, since newlines at the top of the file are undefined behavior. Not sure if that specific heuristic is useful to your use case though.
