masukomi/private-comments-mode

private-comments-mode

private-comment-mode is an emacs plugin for Private Comments allowing you to see and manipulate your private comments from within emacs.

A minor mode for “masukomi/private_comments“. https://github.com/masukomi/private_comments Private comments appear as overlays and are not part of the source.

Install

From Melpa

M-x package-install

Then choose private-comments-mode

From GitHub

$ git clone https://github.com/masukomi/private-comments-mode.git
$ cd private-comments-mode
$ make
# in emacs
M-x package-install-file
# then give it the path to the private-comments-mode-<version>.tar file
# in the dist directory

Usage

Toggle private-comments-mode

M-x private-comments-mode

Add or edit a comment

C-c C-r
; or
private-comments-record

Delete the 1st comment above the cursor

C-c C-d
; or
private-commentns-delete

Keymap (C-h b)

key             binding
---             -------

C-c		Prefix Command
ESC		Prefix Command

C-c C-d		private-comments-delete
C-c C-r		private-comments-record

C-M-q		prog-indent-sexp

Customizing colors

Colors are defined via the private-comments-face. To customize the look, just override its defaults to something that works for you.

Using Emacs’ Easy Customize

The easiest way to customize the look of your private comments is to add a comment, and then run M-x list-faces-display

Search for private-comments-face and select it. Edit the foreground and background colors and click “Apply” to test out new colors. Once you’ve got something you like, click “Apply and Save” to save it for future sessions.

Manual Customization

Choose your favorite foreground and background color combination and add it to your config as follows.

(with-eval-after-load "private-comments-mode"
  (set-face-background 'private-comments-face "#527568")
  (set-face-foreground 'private-comments-face "#FFFFFF"))

Troubleshooting

private-comments-apply: Failed

This error indicates that the file in question has not been committed to git. [The Private Comments system](https://github.com/masukomi/private_comments#readme) uses git commit treeishes to know which comments apply to which versions of a file. As such it can’t work on files that haven’t been committed.

Warning (private-comments): private-comments-apply: Failed
(status 128) git --no-pager ls-files -z --full-name -- my_filename

private-comments-mode's Issues

minor tweaks needed for melpa approval

Feeback on the PR to be included in melpa included the following suggestions

• add SPDX or other license in the private-comments-mode.el file directly
• suggestion to link directly to the private comments server repo in the commentary
• convert some error calls to be user-error (see below 1)
• comment about a progn (see below 2)
• no space in a lighter (see below 3)

The two checked items are addressed in the melpa_tweaks branch.

Details on the unchecked items above. Quoted sections are from the feedback on the melpa PR

1. re. this comment, it wasn't obvious to me which, error calls should be left as-is, so i just didn't change any rather than only making some of the necessary changes.

I think this error: (error "No private comment found") should be user-error; there are a few other places where I'd suggest replacing error with user-error such as in private-comments-delete and private-comments-record -- worth double-checking these (user-errors avoid spilling backtraces to the user)

2. I think this suggestion is incorrect because, as i read it, the 2nd progn in the else but maybe i'm misinterpreting.

I believe the second progn in private-comments--apply-callback shouldn't be required as the "else" part of an if-let

3. I checked the docs re this comment and I saw no mention of anything special about spaces so i have no idea. Also confused as to why this lighter and not the other one. Maybe he just didn't notice the other one.

I think the lighter :lighter " PCM Edit" should avoid having a space with it (spaces are how we usually distinguish between the different lighters)

undeletable comment

⛔ Warning (private-comments): private-comments--generic-callback[ERROR]: Missing required keys. Only had these: ((project_name_hash . 15ab11337cbe15387c49c4d2430c47cca1f42223881c32fe9f535359b7ca1baa) (file_path_hash . 06e34c24d1814e72b5f01023ecf46264e14c7329faa5aa08eb0523c7847091f2) (line_number . 12) (treeish . c26744bc201))

In case anyone else encounters this, the temporary workaround is to

cd ~/.config/private_comments
grep -r "text from comment"
cd <dir containing matching file>
git rm <matching file>
git commit -m "manually removing obsolete comment" 

I think this is a result of rebasing resulting in changed hashes or..... something. Just a guess at this point.

old versions of comments may get "stuck"

Haven't had an opportunity to investigate this as it just happened.

I edited a comment, and that worked as expected, but when the editing window went away i was left with the old version and the new version.

I suspect this is a problem with the code thinking a line is there that isn't anymore or something. Turning PC off and on didn't have an effect. Turning the PC server off an on also didn't have an effect.

🤔 I think it might be useful to enable a "debug mode" in the server that'd spit out all the request data it got...maybe a "logging mode"

The screenshot's kinda 💩because it's a work codebase. Sorry future me (or whoever).

improved line number interaction

Desired behavior

when you comment on a line the private comment should be displayed on the line above it with no line number(s) beside it.

desired behavior

1  <first line of code>
   private comment on line 2
   another line of private comment
2 <second line of code>

Actual behavior

When you comment on a line the private comment has the line number displayed next to the first line of the comment and the line you were commenting on has no line number displayed next to it.

To put it another way, visually, it is taking over the line number's assignment.

actual behavior

1  <first line of code>
2 private comment on line 2
   another line of private comment
   <second line of code>

emacs-virtual-comment and phantom-inline-comment exhibit the same behavior, so maybe this is just a consequence of emacs behavior and not something easily addressed?

Example:

Wrong repository in installation instructions.

The repository given in the installation instructions prompts for a "github" username.

The correct (public) repository URL is: https://github.com/masukomi/private-comments-mode.git