Hi - Thanks for looking at it. I'll respond below...
On 3/26/15, 4:00 PM, "Brad Chamberlain" <[email protected]> wrote: > >Here are my reactions so far: > >* Cute! (if I'm understanding it properly, which I'm not sure I am) I'm glad you see some value in it, even if it's only amusement :) >* Yet... it feels to me like straying too far from what other > C-based/popular languages do in this regard is only inviting trouble. > Is there any precedent for this approach? > > (of course, supporting nested multiline comments in the first place is >a > case of straying that arguably bit you here, though the close comment >in > your pattern would've bitten you for this string even if the nested >open > comment had not) I don't know of any precedent for this one. D uses /** bla bla */ for documentation comments Go uses /* */ and no nesting like C Rust uses /* */ with nesting, and /** */ make doc "attributes" Julia uses #= and =# for nestable multi-line comments Modula-3 and Pascal use (* *) However, I do believe that it would be pretty easy to make a nice error message. for /** */. I found this site http://www.gavilan.edu/csis/languages/comments.html that argues for "mega-comments" that can comment out code with comments. That seems to be what I'm proposing... If we wanted to avoid errors with /** */, we could make only the 3- or 4-star versions have the special behavior. >* At a sniff, the kind of thing I worry about is if I use a very > decorated multi-line comment form like: > > /*********************************************************** > * * > * * > **********************************************************/ > > and have an off-by-one error (as I think the above case does), > then the feature becomes more of an annoyance than a help. > Other than "mistakes" like the above, I don't know whether > there are other standard formatting styles that people use which > are asymmetrical by nature. That kind of thing is not a problem because I limited the counted-stars level to 4. That is, the above comment is interpreted as /**** <commented stuff> ****/ and so it only matters that your first/last 1-4 stars match on the start and end comment. I went up to 4 stars, but I think it would be quite reasonable to stop at 2 or 3... ReplicatedDist.chpl right now has something like /****************************************************************** BLA bla bla bla */ which would be illegal for any variant of the /** thing... So I can't claim that everyone is already writing comments compatible with the idea. But, I can claim that the compiler error will be really easy to understand... >* W.r.t. the specific problem you were trying to work around, does > rst not offer us some other tool by which the desired character > sequence could be represented? Seems like this is an issue that > would be shared by other source-based documentation problems (i.e., > it feels to me like this would be a challenge shared by any source- > based documentation system where they don't have the benefit of > being able to change the language...) I don't know of any way to escape these things in RST. I did search a bit for it earlier and didn't find it... Searching more, I see that \ can escape things. The case I'm talking about has the /*/ inside of an "inline literal" though, and those are one of the two places where \ doesn't escape in RST. So I want it to show ``/*/`` (i.e. /*/ in monospace font). If I put ``/\*\/`` - using backslashes to break up the start and end comment patterns - the RST renders as %/\*\/ ... which is not helpful to me. For Python, they use """ bla bla bla """ for their doc-comments, and these doc-strings use the \ to escape stuff. Since we built our documentation comments on a comment syntax, rather than a string syntax, we don't have any way of escaping things. That said, of course we could pre-process all of our doc-strings to do some kind of escape processing ourselves before RST-ifying. But, I don't like that alternative as much because then we're making up yet another string syntax.... Another approach would be to use a syntax that isn't currently a comment, like /(* *)/ or something..... or /+ +/. Really, the ways to combine punctation are boundless! >* I'm actually also not seeing what it is about your change that > fixes the problem. Is it the case that any nested comments > within a /** ... **/ comment must also use /** ... **/? If so, > that seems to undermine the goal of supporting nested comments, which >is > to be able to throw a comment around a chunk of code without > worrying about whether it contains a comment itself or not. > If not, then I don't see how the /* within the comment is any > better protected than it was before? > > [checking the pull request after reading this, it looks like the "If >so" > case is correct... I didn't get that from the mail, maybe due to > reading too quickly. Also note that the markdown interpretation > of the pull request message made it unreadable in its rendered format] The /*/ (or any single-star comment for that matter) is just treated as regular text within a /** **/ comment. For the /** comment, only **/ will end the comment, and only /** will start a new nested comment. So if you were commenting out some code that already had /* */ comments, you could use /** **/ - and then you would comment it out even if it had malformed /* comments. If it had already /** **/ comments in it, those would remain commented out because of the nested comment processing. Since e.g. /**** ****/ comments blocks are extended /** **/ comments, those also would be handled as nested comments. (thanks for the tip about the pull request - I've fixed it for markdown) >I guess overall at this point, my reaction is that it feels like a big >hammer for solving a little problem that seems intrinsic to >documentation-based comments and that there ought to be a solution that >doesn't require language changes. Have my clarifications helped? Do you have other ideas for how the documentation can have ``/*/`` in it? Or favorites from the alternatives I mentioned? It comes up more often than you'd think (e.g. for shell commands some/path/*/after). I had to change the documentation in 3 cases (to the detriment of the documentation). Thanks, -michael > > >On Wed, 25 Mar 2015, Michael Ferguson wrote: > >> In chpldocing IO.chpl, I needed to describe the %/*/ format >> string, which unfortunately has a nested comment start in it. >> For the documentation for the release, I just put %/ * / and >> then added a comment that the spaces were to be removed. >> >> >> I thought it might be fun to modify the Chapel lexer to >> allow comments to be delimited by a pattern with more stars, >> like /** **/ so that /** /*/ **/ does not have a problem, >> since the inner /* (or */ for that matter) are not interpreted >> as comment start or end. >> >> So I did that just to see if I could get it working. >> I'm quite aware that this is a language change that needs >> to be discussed before the patch can be accepted. >> >> My patch does not change the handling of comments like >> /**/ or /***/ or /****/ etc. There are lots of such comments >> and I wouldn't want to make that illegal... >> >> Lastly, since we're leaning more on the comment syntax for >> chpldoc'ing, I think it makes sense to have comment delimiters >> that are less likely to occur in the comment string, and to >> have a couple of options there in case something comes up. >> >> Any thoughts on this change? A good idea? A bad one? >> >> Thanks, >> >> -michael >> >> P.S. >> >> In case you want to play with the patch, >> you'll have to make parser in compiler/parser to >> get it to actually work (I wanted the pull request to show >> only the real changes). >> >> See >> https://github.com/chapel-lang/chapel/pull/1737 >> >> >> >>------------------------------------------------------------------------- >>----- >> Dive into the World of Parallel Programming The Go Parallel Website, >>sponsored >> by Intel and developed in partnership with Slashdot Media, is your hub >>for all >> things parallel software development, from weekly thought leadership >>blogs to >> news, videos, case studies, tutorials and more. Take a look and join the >> conversation now. http://goparallel.sourceforge.net/ >> _______________________________________________ >> Chapel-developers mailing list >> [email protected] >> https://lists.sourceforge.net/lists/listinfo/chapel-developers >> ------------------------------------------------------------------------------ Dive into the World of Parallel Programming The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/ _______________________________________________ Chapel-developers mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/chapel-developers
