Wrapping C style comments

[Marc Unangst]

I generally format multi-line comments in my C source code like this:

/*
* This is the first line of the comment.
* This is the second line.
* This is the last line.
*/

In Emacs, fill-paragraph (M-q) will automatically find the comment
boundaries and the prefix (" * ") and reflow the comment
appropriately. If there are multiple paragraphs in the comment (i.e.,
blank line except for the prefix) it would keep those paragraphs
separate.

Is there a way to get equivalent behavior from BBEdit's text
wrapping? Neither "Text > Hard Wrap" nor "Text > Rewrap Quoted Text"
seem to do the right thing. Neither of them find the comment
boundaries, and instead rewrap everything between the prior and
subsequent blank line in the source file (for Hard Wrap) or the whole
source file (for Rewrap Quoted) unless I manually select only the
comment. And neither one of them recognizes the line prefix as a
prefix that should be maintained.

Is there a way to get the Emacs-like behavior in BBEdit?

-Marc

[Carlton Gibson]

2008/9/17 Marc Unangst <muna...@gmail.com>

I generally format multi-line comments in my C source code like this:

   /*
    * This is the first line of the comment.
    * This is the second line.
    * This is the last line.
    */

 

Is there a way to get equivalent behavior from BBEdit's text
wrapping?  Neither "Text > Hard Wrap" nor "Text > Rewrap Quoted Text"
seem to do the right thing. 

Hi Marc, 

I have a similar usage and what I do is to start the comment block, using a clipping. I then type my comment, without the *s. 

Next I hard wrap the (uncommented) comment using paragraph fill and apply a text factory to the still selected text which just does a search and replace that looks like this:

Search : (^\s*)(\b)

Replace: \1\* \2

I then close the docblock, with a clipping. 

I also have another clipping for continuing the comment, which is useful if I'm only writing short lines. 

I find that with hot keys set for the clippings this is pretty quick. It is certainly fast enough for me not to think 'I must improve that', although if you do I'd love to hear how! 

Regards,

Carlton

[Marc Unangst]

On Sep 17, 11:19 am, "Carlton Gibson" <carlton.gib...@gmail.com>
wrote:

> I have a similar usage and what I do is to start the comment block, using a
> clipping. I then type my comment, without the *s.

Hi Carlton,

That sounds like it would work when you first write the comment, but
what about revising a comment that's already formatted this way? Do
you also have a text factory to remove the "*" prefixes so you can
rewrap it?

All this seems like a lot of effort for something that Emacs deals
with automatically. (Hint hint, Bare Bones...)

-Marc

[Rich Siegel]

On 9/17/08 at 9:05 PM, muna...@gmail.com (Marc Unangst) wrote:

> All this seems like a lot of effort for something that Emacs deals
> with automatically. (Hint hint, Bare Bones...)

This doesn't resonate with me, because I don't write comments.

R.

(p.s. :-))
--
Rich Siegel Bare Bones Software, Inc.
<sie...@barebones.com> <http://www.barebones.com/>

Someday I'll look back on all this and laugh... until they sedate me.

[Johan™Strandberg]

On Wed, Sep 17, 2008 at 18:10, Rich Siegel <sie...@barebones.com> wrote:

This doesn't resonate with me, because I don't write comments.

R.

(p.s. :-))

(-:  Or balance parenthesis...  :-)

--j

[Dennis]

On Sep 17, 2008, at 6:05 PM, Marc Unangst wrote:

> All this seems like a lot of effort for something that Emacs deals
> with automatically. (Hint hint, Bare Bones...)

I agree and would love to see some enhancements in handling comments.

In the mean time, however, I just use "//" for all my C-style block
comments. The Rewrap Quoted Text command works nicely with them and
double slashes happen to be the standard coding style in my group
anyway. :-)

-Dennis

[Mike Conley]

I'll just chime in with my own personal prejudice and point out that I
truly loath any style of comments that insists on putting something at
the beginning of each line (*, //, whatever) of comment text. It's
cluttered, makes it next to impossible to edit the text by hand, and
requires extra effort on the part of editor software to handle
correctly to do automatic reformatting.

Syntax-colouring is available, which serves to highlight comments. All
that's needed is a /* before the first line and a */ afterward, and
there you go. Simple and clean.

Assign a keyboard shortcut (mine's command-option-\) to Text > Hard
Wrap, and reformatting is straightforward.

In fact, I even have a script to reformat silly //-delimited comments
and convert them to my desired format. Use at your own risk.

(*
Update this to match the default wrap width.
*)
set wrapWidth to 80

tell application "BBEdit"
set selectedText to selection of text window 1 as string
if selectedText is not "" then
(*
Record the starting and ending line numbers of the selection so
that we can restore the selection after the replacement. The
replacement will remove characters from the selection, and the
selected area may encroach upon the next line, which will screw up the
remaining replacement operations.
*)
set startLn to startLine of selection of text window 1
set endLn to endLine of selection of text window 1
set endLn to endLn - 1

(*
Get rid of the // comment delimiters.
*)
replace "^(\\s*)//\\s*(.*$)" using "\\1\\2" searching in selection
of text window 1 options {search mode:grep, starting at top:false,
wrap around:false, backwards:false, case sensitive:false, match
words:false, extend selection:false}

(*
Re-select the original lines.
*)
select lines startLn thru endLn of text window 1

(*
Trim trailing whitespace.
*)
replace "\\s+\\r" using "\\r" searching in selection of text window
1 options {search mode:grep, starting at top:true, wrap around:false,
backwards:false, case sensitive:false, match words:false, extend
selection:false}

(*
Re-select the original lines.
*)
select lines startLn thru endLn of text window 1

(*
Trim all blank lines before or after the actual comment body. We
need to recalculate the index to the last line of the selection as
each blank line is deleted, and then reselect the text, since the
delete command deselects the text
*)
repeat while (line startLn of text window 1) as string is ""
delete line startLn of text window 1
set endLn to endLn - 1
end repeat

repeat while (line endLn of text window 1) as string is ""
delete line endLn of text window 1
set endLn to endLn - 1
end repeat

(*
It's often the case that the first character in the comment is not
capitalized as it should be; make it so. Search only the first line of
the commment, as we don't want to capitalize all of them.
*)
select lines startLn thru startLn of text window 1
replace "^(\\s*)(\\w)" using "\\1\\u\\2" searching in selection of
text window 1 options {search mode:grep, starting at top:false, wrap
around:false, backwards:false, case sensitive:false, match
words:false, extend selection:false}

(*
It's also often the case that the last line of the comment does not
have a full stop or any other punctuation. If this is the case, add a
full stop.
*)
select lines endLn thru endLn of text window 1
replace "(\\w)$" using "\\1\\." searching in selection of text
window 1 options {search mode:grep, starting at top:false, wrap
around:false, backwards:false, case sensitive:false, match
words:false, extend selection:false}

(*
Reselect the entire set of comment lines and rewrap the comment
text. Recalculate the line offsets, as the rewrap may have changed the
number of lines.
*)
select lines startLn thru endLn of text window 1

hard wrap selection of text window 1 limit character width width
wrapWidth indentation same_as_first_line with paragraph fill and
relative
set startLn to startLine of selection of text window 1
set endLn to endLine of selection of text window 1
set endLn to endLn - 1

(*
Finally, put /* */ delimeters before and after the entire comment
block, the way it's supposed to be. Note that we do the terminating
delimiter first because inserting it will change the line indices, and
it saves having to recalculate <endLn> again.

Also note that we have to insert the proper amount of leading
whitespace, so we first do a search on the first line to extract that.
*)
find "^(\\s*)" searching in selection of text window 1 options
{search mode:grep, starting at top:false, wrap around:false,
backwards:false, case sensitive:false, match words:false, extend
selection:false}
set leadSpace to found text of result

select insertion point after line endLn of text window 1
set selection to (return & leadSpace & "*/") as string

select insertion point before line startLn of text window 1
set selection to (leadSpace & "/*" & return) as string

end if
end tell

[Carlton Gibson]

2008/9/18 Marc Unangst <muna...@gmail.com>

On Sep 17, 11:19 am, "Carlton Gibson" <carlton.gib...@gmail.com>
wrote:

> I have a similar usage and what I do is to start the comment block, using a
> clipping. I then type my comment, without the *s.

Hi Carlton,

That sounds like it would work when you first write the comment, but
what about revising a comment that's already formatted this way?  Do
you also have a text factory to remove the "*" prefixes so you can
rewrap it?

You don't need to. 

Say you've got a paragraph half way up your comment. Just edit it. Then rewrap that bit and apply the text factory. 

If you did need to, removing "*"s would be trivial -- just rework the search and replace from my last post.

 

All this seems like a lot of effort for something that Emacs deals
with automatically.  (Hint hint, Bare Bones...)

A couple of key strokes ain't hard (IMHO :-)

BBEdit allows you to extend its functionality with a filter or an AppleScript or a Text Factory to do anything you want -- add/remove C-style block comments included. (It's either easy to implement filters etc or else it's a good exercise, depending on experience.)

Bare Bones **definitely should not** (again IMHO) start implementing multiple commenting styles as built-in commands unless they can specify in advance where it would stop.

Just from this example, you use:

   /*
    * This is the first line of the comment.
    * This is the second line.
    * This is the last line.
    */

But I use:

   /**

    * This is the first line of the comment.
    * This is the second line.
    * This is the last line.
    */

A subtle difference but to keep us happy BB would have to implement both. But commenting styles are a most personal thing; there are as many styles as there are coders. So is BB going to implement them all? 

Once started on this road, we might very well end up with the world's best code comment generator (just the syntax mind) but it is very unlikely it would still be the world's best text editor. 

Regards,

Carlton

p.s. Whilst typing this it seems Mike has demonstrated my point.

p.p.s. Can BBEdit's balancing-thingy not recognise a smiley and stop shouting "unmatched" at me...? 

[Carlton Gibson]

Correction:

I use:

   /**

    * This is the first line of the comment.
    * This is the second line.
    * This is the last line.
    */

Not:

[Lewis@Gmail]

On 18-Sep-2008, at 02:45, Carlton Gibson wrote:
> /**
> * This is the first line of the comment.
> * This is the second line.
> * This is the last line.
> */

I used to use this format, but with syntax coloring, it seems kind of
pointless.

/*
Comments go here
on multiple lines
*/

Shows up as an obvious comment not only in bbedit, but in vim as well.

--
"Katrina, $4 gas, a trillion dollar war, rising unemployment,
deregulated housing market, global warming...NO MORE!"
http://is.gd/2mxY

[Carlton Gibson]

2008/9/19 Lewis@Gmail <gkr...@gmail.com>

On 18-Sep-2008, at 02:45, Carlton Gibson wrote:
>   /**
>    * This is the first line of the comment.
>    * This is the second line.
>    * This is the last line.
>    */

I used to use this format, but with syntax coloring, it seems kind of
pointless.

/*
  Comments go here
  on multiple lines
*/

Shows up as an obvious comment not only in bbedit, but in vim as well.

Ah, what a fine world it would be if all development tools and coding standards were built around BBEdit's syntax colouring!!! :-)