Add doctest editing command

[Aankhen]

Adds a command rust-edit-doctest (bound to C-c C-e by default) that opens the doctest around point in an indirect buffer and pre– as well as postprocesses it to ease editing. The indirect buffer is placed in a new rust-doctest-mode that recognizes a leading hash as a comment character. After editing, the code is replaced in the original file and the region is re-indented. Here’s a screenshot:

This is all accomplished using edit-indirect. If that package is not loaded, the keybinding is not added. I initially placed the definition of the rust-edit-doctest command itself under a conditional, but then I thought it would be more useful to have the command show an explanatory error in case it’s missing.

rust-doctest-mode doesn’t account for escaped hashes. I’m not sure how to implement that. Any suggestions would be welcome!

[Aankhen]

Added support for doctests in crate-level documentation and squashed it down to one commit to make it more manageable.

[nikomatsakis]

This sounds neat.

[0x3UH4224D]

Cool feature.
Another thing that would be cool too is to add a way to edit the docs in separate frame. just like this PR but for the docs. something like this:

I'm not sure if I need to open a new issue since this PR is doing something similar.

[Aankhen]

Given that it’s been 10 months, I don’t think this PR will be merged, heh. You may be better off opening a new one.

[otavio]

It is not clear to me why it is taking so long for this PR to be reviewed and possibly merged. It does improve the usability and makes it more convenient to write the docs, which is an important aspect of Rust ecosystem.

Could someone take a look at it?

[pnkfelix]

I’ll try to take a look at this this week

[antifuchs]

Not knowing that this PR exists, I replicated almost exactly the thing that this PR does, except for rustdoc comments, also using edit-indirect (I believe this is what @0x3UH4224D asked for?), as a proof of concept: https://gist.github.com/antifuchs/aa9fa4c3d1354ea163bc13e63d32db1a

@Aankhen - I would love if we could merge both our work and either get this merged or failing that, release it as a separate package.

[otavio]

I moved to rustic-mode. It would be a nice candidate for this contribution 🙏

[Aankhen]

@antifuchs: That’s very cool, and yes, it does sound like what @0x3UH4224D was asking for! I’d love to merge them or release them as a separate package. I can’t quite figure out whether edit-indirect can handle nested indirect edits. If it can, we may not need to do much to merge them. Do you have any idea?

@otavio: I don’t know much about rustic-mode, but maybe we could look at that once we have this PR working somewhere.

[antifuchs]

I think one of the things we could do is to have two different edit commands, so we get pop-ups directly from the rust buffer (I believe nested edit-indirections might work, but popping them down should probably happen in the right order).

From my recent experience with rustic (and judging from comments about rust-mode's maintenance situation), I think it might be better to make a separate package - should also make it easier to have dependencies that aren't vital for the rust-mode package.

I'll try and merge our two pieces by next weekend into a separate package and will make you a contributor once I have something ready!

[Fanael]

I can’t quite figure out whether edit-indirect can handle nested indirect edits.

Depends on what exactly you mean by "nested". You cannot have multiple overlapping indirect regions of one buffer at the same time, but you can call edit-indirect-region in an edit-indirect buffer just fine.

If you mean the former, I may add support for overlapping indirect regions if you can show me a use case for which it makes sense, because it would mostly be a matter of relaxing one check.

[Aankhen]

@antifuchs: All of that makes sense; separate commands is indeed what I was thinking, and nested edit-indirect calls were what I was referring to. As far as merging them into a single package goes, that sounds great—thank you very much!

@Fanael: Thanks for the clarification! I meant the latter (calling edit-indirect-region in an edit-indirect buffer, so it seems like we’re fine. I don’t think it would make sense to have multiple overlapping indirect regions, at least not here.

[mezeipetister]

Hi Guys, do you plan to merge this function, and make it available for everybody as standard rust-mode feature? It would be great!

[mookid]

Hey @Aankhen, would you consider working on that PR again?

[Aankhen]

Hi @mookid. Sure, I’ve updated it and double-checked that the tests pass.

[antifuchs]

So the other day I saw a comment on the gist above that points to https://github.com/twlz0ne/comment-edit.el - a more generic comment-editing mode that handles rust doc comments (and the contained rust examples!) quite well. These days, I'd probably recommend this over solutions custom-built for a single language (:

[mookid]

hi @Aankhen

I completely missed your message. I'll take a look at the whole story as soon as I get some time.

[Aankhen]

So the other day I saw a comment on the gist above that points to https://github.com/twlz0ne/comment-edit.el - a more generic comment-editing mode that handles rust doc comments (and the contained rust examples!) quite well. These days, I'd probably recommend this over solutions custom-built for a single language (:

That looks very cool. Thanks for sharing the link here! I take it you’ve been using it and had no issues with Rust doc comments?

[Aankhen]

I’ll assume that’s a yes, so, since this isn’t being merged and there’s a better, more generally applicable alternative, I’m going to close this PR.