[PATCH] org: Update example in docstring to accommodate new name and new format

[PATCH] org: Update example in docstring to accommodate new name and new format

[Leo Vivier]

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

Hi there,

I’ve spotted an example in a docstring that wasn’t updated when the
command was renamed and moved to another file in
d34786f2279d0fd02e7d0484e36bc22adc760de2.

I took the liberty to update it.

HTH,

-- 
Leo Vivier

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-Update-docstring.patch --]
[-- Type: text/x-patch, Size: 822 bytes --]

From 83dde9d0735cc6223233aa18c938a4ae14b4c88c Mon Sep 17 00:00:00 2001
From: Leo Vivier <leo.vivier+dev@gmail.com>
Date: Mon, 20 Jul 2020 22:11:15 +0200
Subject: [PATCH] org: Update docstring

* lisp/org.el (org-find-olp): Update example in docstring to
accommodate new name and new format
---
 lisp/org.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/org.el b/lisp/org.el
index 12a853bd6..5900e692a 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -13501,7 +13501,7 @@ If anything goes wrong, throw an error.
 You can wrap this call to catch the error like this:
 
   (condition-case msg
-      (org-mobile-locate-entry (match-string 4))
+      (org-find-olp (list (match-string 4) t)
     (error (nth 1 msg)))
 
 The return value will then be either a string with the error message,
-- 
2.26.2

Re: [PATCH] org: Update example in docstring to accommodate new name and new format

[Leo Vivier]

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

Hi again,

I forgot a closing paren in the previous commit.  You’ll find an amended
version below, as well as a little more context-lines.  Sorry!

HTH,

-- 
Leo Vivier

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-Update-docstring.patch --]
[-- Type: text/x-patch, Size: 1353 bytes --]

From 01acc00866f14a6e70e3abcb024534c392dc8a27 Mon Sep 17 00:00:00 2001
From: Leo Vivier <leo.vivier+dev@gmail.com>
Date: Mon, 20 Jul 2020 22:11:15 +0200
Subject: [PATCH] org: Update docstring

* lisp/org.el (org-find-olp): Update example in docstring to
accommodate new name and new format
---
 lisp/org.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lisp/org.el b/lisp/org.el
index 12a853bd6..a5d552fc0 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -13494,21 +13494,21 @@ completion."
 	(setq org-clock-effort nval)
 	(org-clock-update-mode-line)))
     (run-hook-with-args 'org-property-changed-functions key nval)))
 
 (defun org-find-olp (path &optional this-buffer)
   "Return a marker pointing to the entry at outline path OLP.
 If anything goes wrong, throw an error.
 You can wrap this call to catch the error like this:
 
   (condition-case msg
-      (org-mobile-locate-entry (match-string 4))
+      (org-find-olp (list (match-string 4)) t)
     (error (nth 1 msg)))
 
 The return value will then be either a string with the error message,
 or a marker if everything is OK.
 
 If THIS-BUFFER is set, the outline path does not contain a file,
 only headings."
   (let* ((file (if this-buffer buffer-file-name (pop path)))
 	 (buffer (if this-buffer (current-buffer) (find-file-noselect file)))
 	 (level 1)
-- 
2.26.2

Re: [PATCH] org: Update example in docstring to accommodate new name and new format

[Kyle Meyer]

Leo Vivier writes:

> I’ve spotted an example in a docstring that wasn’t updated when the
> command was renamed and moved to another file in
> d34786f2279d0fd02e7d0484e36bc22adc760de2.

Thanks for the patch and for digging back to the commit that moved
org-find-olp.  Looking at that commit, I'm a bit confused because the
example was introduced with that commit (i.e. it didn't just go stale
with the move).  Also the function has the same name, org-find-olp, both
before and after that commit.

Anyway, in my view the example doesn't really add much value.  What do
you think about just removing it?

Re: [PATCH] org: Update example in docstring to accommodate new name and new format

[Leo Vivier]

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

Hi there,

Kyle Meyer <kyle@kyleam.com> writes:

> Anyway, in my view the example doesn't really add much value.  What do
> you think about just removing it?

Yeah, I agree.  I thought it was an interesting way to discover
`condition-case' for those who didn’t know about it, so I think we could
keep the mention.  The example itself can go.

Thanks for the review.

HTH,

-- 
Leo Vivier

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-org-Remove-useless-example-in-docstring.patch --]
[-- Type: text/x-patch, Size: 1687 bytes --]

From 48b50f0ebb5d21ca6b337d78a16a203888161d43 Mon Sep 17 00:00:00 2001
From: Leo Vivier <leo.vivier+dev@gmail.com>
Date: Mon, 20 Jul 2020 22:11:15 +0200
Subject: [PATCH] org: Remove useless example in docstring

* lisp/org.el (org-find-olp): Remove useless example in docstring
---
 lisp/org.el | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/lisp/org.el b/lisp/org.el
index 12a853bd6..9ac513d0c 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -13490,29 +13490,23 @@ completion."
        '((effort . identity)
 	 (effort-minutes . org-duration-to-minutes))
        nval)
       (when (string= org-clock-current-task heading)
 	(setq org-clock-effort nval)
 	(org-clock-update-mode-line)))
     (run-hook-with-args 'org-property-changed-functions key nval)))
 
 (defun org-find-olp (path &optional this-buffer)
   "Return a marker pointing to the entry at outline path OLP.
-If anything goes wrong, throw an error.
-You can wrap this call to catch the error like this:
-
-  (condition-case msg
-      (org-mobile-locate-entry (match-string 4))
-    (error (nth 1 msg)))
-
-The return value will then be either a string with the error message,
-or a marker if everything is OK.
+If anything goes wrong, throw an error, and if you need to do
+something based on this error, you can catch it with
+`condition-case'.
 
 If THIS-BUFFER is set, the outline path does not contain a file,
 only headings."
   (let* ((file (if this-buffer buffer-file-name (pop path)))
 	 (buffer (if this-buffer (current-buffer) (find-file-noselect file)))
 	 (level 1)
 	 (lmin 1)
 	 (lmax 1)
 	 end found flevel)
     (unless buffer (error "File not found :%s" file))
-- 
2.26.2

Re: [PATCH] org: Update example in docstring to accommodate new name and new format

[Kyle Meyer]

Leo Vivier writes:

> Subject: [PATCH] org: Remove useless example in docstring
>
> * lisp/org.el (org-find-olp): Remove useless example in docstring

Thanks.  Applied (c9abb4c29), adding a period after the changelog
description.

I also added a TINYCHANGE cookie based on your status listed at
<https://orgmode.org/worg/org-contribute.html>.  You're bumping up
against the tiny change threshold, so please consider submitting the
copyright assignment paperwork.

Re: [PATCH] org: Update example in docstring to accommodate new name and new format

[Leo Vivier]

Hi there,

Kyle Meyer <kyle@kyleam.com> writes:

> Thanks.  Applied (c9abb4c29), adding a period after the changelog
> description.

Splendid, thank you for the merge, and sorry for the period.

> I also added a TINYCHANGE cookie based on your status listed at
> <https://orgmode.org/worg/org-contribute.html>.  You're bumping up
> against the tiny change threshold, so please consider submitting the
> copyright assignment paperwork.

I have already filled the paperwork, and I will send you the scan in
a separate email.  Could you move me to the list of current
contributors?

Thanks.

Best,

-- 
Leo Vivier

Re: [PATCH] org: Update example in docstring to accommodate new name and new format

[Kyle Meyer]

Leo Vivier writes:

> I have already filled the paperwork, and I will send you the scan in
> a separate email.  Could you move me to the list of current
> contributors?

Sorry for the mix-up.  Updated.