[PATCH v1 1/4] contrib/lisp/org-annotate-file.el improvements

[PATCH v1 1/4] contrib/lisp/org-annotate-file.el improvements

[David Holm]

[-- Attachment #1.1: Type: text/plain, Size: 1248 bytes --]

Hi All,
I was looking for a way to annotate code in Emacs for code reviews and
found a post on Stack Overflow recommending org-annotate-file [1].  This
was pretty close to what I was looking for but with two exceptions,
 * I wanted to be able to store the annotations in different files
depending on the project and
 * I wanted the write my comments in a popup window.

In order to accomplish this I have modified org-annotate-file so that the
storage file is passed as a parameter to `org-annotate-file-show-section`
and only `org-annotate-file` directly use the variable
`org-annotate-file-storage-file`.  I also changed
`org-annotate-file-show-section` to return the annotation buffer rather
than switching to it.  `org-annotate-file` will just pass it to
`switch-to-buffer` but in my personal configuration I instead hand it off
to popwin so that it is shown as a popup:

   (popwin:display-buffer-1 (org-annotate-file-show-section storage-file)
                             :default-config-keywords '(:position :bottom))

This first patch just fixes some of the docstrings in order to satisfy
Flycheck.

Best regards,
David Holm

 [1]:
http://stackoverflow.com/questions/8148842/code-review-mode-package-for-emacs-with-good-reporting-function

[-- Attachment #1.2: Type: text/html, Size: 1584 bytes --]

[-- Attachment #2: 0001-Fix-issues-detected-by-CheckDoc.patch --]
[-- Type: application/octet-stream, Size: 4655 bytes --]

From 94c88c3bfe522db652f2c7e5a68768510c16d3d1 Mon Sep 17 00:00:00 2001
From: David Holm <dholmster@gmail.com>
Date: Sat, 15 Mar 2014 16:50:04 +0100
Subject: [PATCH 1/4] Fix issues detected by CheckDoc

* lisp/contrib/org-annotate-file.el: Fixes the style of the
documentation to make Emacs CheckDoc happy.

TINYCHANGE
---
 contrib/lisp/org-annotate-file.el | 35 ++++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/contrib/lisp/org-annotate-file.el b/contrib/lisp/org-annotate-file.el
index 05cc45f..0d41574 100644
--- a/contrib/lisp/org-annotate-file.el
+++ b/contrib/lisp/org-annotate-file.el
@@ -25,7 +25,7 @@
 ;;; Commentary:
 
 ;; This is yet another implementation to allow the annotation of a
-;; file without modification of the file itself. The annotation is in
+;; file without modification of the file itself.  The annotation is in
 ;; org syntax so you can use all of the org features you are used to.
 
 ;; To use you might put the following in your .emacs:
@@ -47,30 +47,31 @@
 ;; and next time you hit C-c C-l you will hit those notes again.
 ;;
 ;; To put a subheading with a text search for the current line set
-;; `org-annotate-file-add-search` to non-nil value. Then when you hit
+;; `org-annotate-file-add-search` to non-nil value.  Then when you hit
 ;; C-c C-l (on the above line for example) you will get:
 
 ;; * ~/org-annotate-file.el
-;; ** `org-annotate-file-add-search` to non-nil value. Then whe...
+;; ** `org-annotate-file-add-search` to non-nil value.  Then whe...
 
 ;; Note that both of the above will be links.
 
+;;; Code:
+
 (require 'org)
 
 (defvar org-annotate-file-storage-file "~/.org-annotate-file.org"
   "File in which to keep annotations.")
 
 (defvar org-annotate-file-add-search nil
-  "If non-nil then add a link as a second level to the actual
-location in the file")
+  "If non-nil, add a link as a second level to the actual file location.")
 
 (defvar org-annotate-file-always-open t
-  "non-nil means always expand the full tree when you visit
-`org-annotate-file-storage-file'.")
+  "If non-nil, always expand the full tree when visiting the annotation file.")
 
-(defun org-annotate-file-elipsify-desc (string &optional after)
-  "Strip starting and ending whitespace and replace any chars
-that appear after the value in `after' with '...'"
+(defun org-annotate-file-ellipsify-desc (string &optional after)
+  "Return shortened STRING with appended ellipsis.
+Trim whitespace at beginning and end of STRING and replace any
+  characters that appear after the occurrence of AFTER with '...'"
   (let* ((after (number-to-string (or after 30)))
          (replace-map (list (cons "^[ \t]*" "")
                             (cons "[ \t]*$" "")
@@ -83,21 +84,23 @@ that appear after the value in `after' with '...'"
     string))
 
 (defun org-annotate-file ()
-  "Put a section for the current file into your annotation file"
+  "Put a section for the current file into your annotation file."
   (interactive)
   (unless (buffer-file-name)
-    (error "This buffer has no associated file"))
+    (error "This buffer has no associated file!"))
   (org-annotate-file-show-section))
 
 (defun org-annotate-file-show-section (&optional buffer)
-  "Visit the buffer named `org-annotate-file-storage-file' and
-show the relevant section"
+  "Visit the buffer named `org-annotate-file-storage-file'.
+The cursor will be placed at the relevant section.  If BUFFER is
+  specified the annotation will be referencing it, otherwise the
+  current buffer is used."
   (let* ((filename (abbreviate-file-name (or buffer (buffer-file-name))))
          (line (buffer-substring-no-properties (point-at-bol) (point-at-eol)))
          (link (org-make-link-string (concat "file:" filename) filename))
          (search-link (org-make-link-string
                        (concat "file:" filename "::" line)
-                               (org-annotate-file-elipsify-desc line))))
+                               (org-annotate-file-ellipsify-desc line))))
     (with-current-buffer (find-file org-annotate-file-storage-file)
       (unless (eq major-mode 'org-mode)
         (org-mode))
@@ -117,11 +120,13 @@ show the relevant section"
           (org-annotate-file-add-second-level search-link))))))
 
 (defun org-annotate-file-add-upper-level (link)
+  "Add and link heading to LINK."
   (goto-char (point-min))
   (call-interactively 'org-insert-heading)
   (insert link))
 
 (defun org-annotate-file-add-second-level (link)
+  "Add and link subheading to LINK."
   (goto-char (point-at-eol))
   (call-interactively 'org-insert-subheading)
   (insert link))
-- 
1.9.0

Re: [PATCH v1 1/4] contrib/lisp/org-annotate-file.el improvements

[Bastien]

Hi David,

thanks for the patches, I applied them all.

If you want direct commit access to tweak org-annotate-file.el,
please send me your public key.

Thanks!

-- 
 Bastien