bug#17978: 24.3; forward-paragraph broken with javadocs

bug#17978: 24.3; forward-paragraph broken with javadocs

[Justine Tunney]

[-- Attachment #1: Type: text/plain, Size: 563 bytes --]

The default emacs behavior for the forward-paragraph and
backward-paragraph functions is to hop between blank lines in a source
code file. This breaks in java-mode in the presence of javadoc @clauses.

I sent a pull request to the js2-mode project (which also supports
javadocs, and thus the same error occurs) but it was rejected since they
told me it was an emacs bug.

Here's the pull request I sent the js2-mode authors:
https://github.com/mooz/js2-mode/pull/147

Here's the video explanation I gave the js2-mode authors:
http://youtu.be/cXerimuxNK8

Thanks!

[-- Attachment #2: Type: text/html, Size: 864 bytes --]

bug#17978: 24.3; forward-paragraph broken with javadocs

[Stefan Monnier]

> The default emacs behavior for the forward-paragraph and
> backward-paragraph functions is to hop between blank lines in a source
> code file. This breaks in java-mode in the presence of javadoc @clauses.

In which sense does it "break"?  Can you show some example code and the
behavior you expect compared to the behavior you get?


        Stefan

bug#17978: 24.3; forward-paragraph broken with javadocs

[Justine Tunney]

[-- Attachment #1: Type: text/plain, Size: 681 bytes --]

I included a video explanation: http://youtu.be/cXerimuxNK8

The same problem I demonstrate in the video, also applies to java-mode.
When you hit C-{ and C-}, rather than go to the next blank line, it'll go
to @tags in javadocs.


On Wed, Jul 9, 2014 at 3:26 PM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > The default emacs behavior for the forward-paragraph and
> > backward-paragraph functions is to hop between blank lines in a source
> > code file. This breaks in java-mode in the presence of javadoc @clauses.
>
> In which sense does it "break"?  Can you show some example code and the
> behavior you expect compared to the behavior you get?
>
>
>         Stefan
>

[-- Attachment #2: Type: text/html, Size: 1167 bytes --]

bug#17978: 24.3; forward-paragraph broken with javadocs

[Stefan Monnier]

> I included a video explanation: http://youtu.be/cXerimuxNK8

Could you just send plain text showing an example piece of code, then
a command you use on it, the end result you get and the end result you'd
like to get instead?

That's surely easier to do, and will save me the trouble of dealing with
videos which I find unbearable (you can't just look at them, you have to
additionally listen to them; if you get distracted along the way you end
up having to start over; half the time there's a technical problem; you
can't choose the speed at which you "read/view", so you have to wait
for irrelevant crap before getting to the point; it's a huge waste of
bandwidth).


        Stefan

bug#17978: 24.3; forward-paragraph broken with javadocs

[Justine Tunney]

[-- Attachment #1: Type: text/plain, Size: 1672 bytes --]

Assume that I have the following Java source, where # indicates the cursor
position:

/**
 * Does stuff.
 *
 * <p>Hello
 *
 * @see FooBar
 */
private void lol() {}
#


So I press C-{ and this is what happens:


/**
 * Does stuff.
 *
 * <p>Hello
 *
#* @see FooBar
 */
private void lol() {}


And then I press it again:


/**
 * Does stuff.
 *
#* <p>Hello
 *
 * @see FooBar
 */
private void lol() {}


And here's what I expected to happen:


#
/**
 * Does stuff.
 *
 * <p>Hello
 *
 * @see FooBar
 */
private void lol() {}


C-{ and C-} should cycle between blank lines. But the reason why this
doesn't happen in java-mode, is because Java redefines the definition of a
paragraph. It sets the paragraph-start variable (among other variables) so
that when I M-q to fill-paragraph, it'll work correctly *within* the
Javadoc, rather than reflowing my code into a jumbled mess.


On Wed, Jul 9, 2014 at 6:28 PM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > I included a video explanation: http://youtu.be/cXerimuxNK8
>
> Could you just send plain text showing an example piece of code, then
> a command you use on it, the end result you get and the end result you'd
> like to get instead?
>
> That's surely easier to do, and will save me the trouble of dealing with
> videos which I find unbearable (you can't just look at them, you have to
> additionally listen to them; if you get distracted along the way you end
> up having to start over; half the time there's a technical problem; you
> can't choose the speed at which you "read/view", so you have to wait
> for irrelevant crap before getting to the point; it's a huge waste of
> bandwidth).
>
>
>         Stefan
>

[-- Attachment #2: Type: text/html, Size: 3070 bytes --]

bug#17978: 24.3; forward-paragraph broken with javadocs

[Stefan Monnier]

> C-{ and C-} should cycle between blank lines. But the reason why this
> doesn't happen in java-mode, is because Java redefines the definition of a
> paragraph. It sets the paragraph-start variable (among other variables) so
> that when I M-q to fill-paragraph, it'll work correctly *within* the
> Javadoc, rather than reflowing my code into a jumbled mess.

Ah, I see, yes, that makes sense.  The fix is to not change
paragraph-start (and friends) in the major-mode hook but instead to
define override the fill-forward-paragraph-function with a function
which let-binds those vars and then calls forward-paragraph.

See lisp/vc/add-log.el for an example.


        Stefan

bug#17978: 24.3; forward-paragraph broken with javadocs

[Dmitry]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> C-{ and C-} should cycle between blank lines. But the reason why this
>> doesn't happen in java-mode, is because Java redefines the definition of a
>> paragraph. It sets the paragraph-start variable (among other variables) so
>> that when I M-q to fill-paragraph, it'll work correctly *within* the
>> Javadoc, rather than reflowing my code into a jumbled mess.
>

Hi Stefan,

> Ah, I see, yes, that makes sense.  The fix is to not change
> paragraph-start (and friends) in the major-mode hook but instead to
> define override the fill-forward-paragraph-function with a function
> which let-binds those vars and then calls forward-paragraph.

Thanks for the vertict, I'll fix that in js2-mode, 

This doesn't look straightforward to do, though: the final
`paragraph-start' is obtained by calling `c-setup-paragraph-variables',
so to get the value computed both ways, guess we'll have to call it at
least twice.

bug#17978: 24.3; forward-paragraph broken with javadocs

[Dmitry]

Dmitry <dgutov@yandex.ru> writes:

> This doesn't look straightforward to do, though: the final
> `paragraph-start' is obtained by calling `c-setup-paragraph-variables',
> so to get the value computed both ways, guess we'll have to call it at
> least twice.

Or maybe we should save the computed value, but then kill the
buffer-local value of `paragraph-start'?

This actually seems to be what Justine is asking for, because the
"unexpected" paragraph movement happens not just because of javadocs,
but also due to the "empty" lines within the comment.

`c-setup-paragraph-variables' intentionally sets the variable up this
way, so maybe we should consider more carefully whether
`backward-paragraph' should stop at those lines.

bug#17978: 24.3; forward-paragraph broken with javadocs

[Stefan Monnier]

> Or maybe we should save the computed value, but then kill the
> buffer-local value of `paragraph-start'?

That's probably the most straightforward solution, yes.

> `c-setup-paragraph-variables' intentionally sets the variable up this
> way, so maybe we should consider more carefully whether
> `backward-paragraph' should stop at those lines.

Paragraph movement within code is "non standard": I'm sure some users
use it regularly, but I'd expect the vast majority never uses it, and
all programming major modes I know don't seem to care about
paragraph movement.  Many do care about paragraph filling, tho.
So I'm pretty sure that the paragraph-* settings here are meant
specifically for filling and not for movement.


        Stefan

bug#17978: 24.3; forward-paragraph broken with javadocs

[Dmitry Gutov]

On 07/11/2014 04:51 PM, Stefan Monnier wrote:
>> Or maybe we should save the computed value, but then kill the
>> buffer-local value of `paragraph-start'?
>
> That's probably the most straightforward solution, yes.

Seems like it would need to be done in `c-setup-paragraph-variables' for 
all CC Engine modes, if done at all. So the choice is probably up to its 
maintainer.

Alan, what do you think?

bug#17978: 24.3; forward-paragraph broken with javadocs

[Alan Mackenzie]

Hi, Justine, Hi, Dmitry and Stefan.

On Sun, Jul 13, 2014 at 03:48:13AM +0300, Dmitry Gutov wrote:
> On 07/11/2014 04:51 PM, Stefan Monnier wrote:
> >> Or maybe we should save the computed value, but then kill the
> >> buffer-local value of `paragraph-start'?

> > That's probably the most straightforward solution, yes.

> Seems like it would need to be done in `c-setup-paragraph-variables' for 
> all CC Engine modes, if done at all. So the choice is probably up to its 
> maintainer.

> Alan, what do you think?

With all due respect to the OP, the purpose of C-{ and C-} is to move
between paragraphs, not blank lines.  Or, alternatively, in CC Mode, a
line which contains only a comment prefix is considered to be blank.

The motivation for this is to be able to move by paragraphs in large
comments, such are frequently found at the beginning of source files.
Sometimes, comments for individual functions are also quite sizeable.
And of course, as already mentioned, filling should do the Right Thing
inside comments.  If backward-paragraph (and forward-paragraph) were to
be redefined not to handle comment prefices specially, the facility to
move by paragraphs inside large comments (when the comment prefix is
non-null) would be lost.

I don't think we should change things here.

Maybe what we really need is commands beginning-of-comment and
end-of-comment.

As an alternative to C-{, there's always M-- C-M-e (move to the end of
the previous function) which does almost the same thing in the OP's
particular use case, and is only slightly more awkward to type.

-- 
Alan Mackenzie (Nuremberg, Germany).

bug#17978: 24.3; forward-paragraph broken with javadocs

[Lars Ingebrigtsen]

Alan Mackenzie <acm@muc.de> writes:

> With all due respect to the OP, the purpose of C-{ and C-} is to move
> between paragraphs, not blank lines.  Or, alternatively, in CC Mode, a
> line which contains only a comment prefix is considered to be blank.
>
> The motivation for this is to be able to move by paragraphs in large
> comments, such are frequently found at the beginning of source files.
> Sometimes, comments for individual functions are also quite sizeable.
> And of course, as already mentioned, filling should do the Right Thing
> inside comments.  If backward-paragraph (and forward-paragraph) were to
> be redefined not to handle comment prefices specially, the facility to
> move by paragraphs inside large comments (when the comment prefix is
> non-null) would be lost.
>
> I don't think we should change things here.

(I'm going through old bug reports that unfortunately weren't resolved
at the time.)

Skimming this bug report, it sounds like this is working as designed, so
I'm therefore closing this bug report.  If further work should be done
here, please respond to the debbugs address and we'll reopen.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no