AFAICT, there is no place in the manual that explains what is the
RESULTS keyword
OK, may be that's the first step :)
and under what circumstances it could be useful to write
it manually.
No, I wasn't suggesting a use case where someone writes the #+RESULTS: contents manually.
Here's what can happen though:
A user could have this to begin with:
=====
#+BEGIN_SRC emacs-lisp
(message "Hello")
#+END_SRC
#+RESULTS:
: Hello
| some | thing | important |
=====
Then for whatever reason, they choose to delete the RESULTS manually.. and the blank line after that too!
=====
#+BEGIN_SRC emacs-lisp
(message "Hello")
#+END_SRC
#+RESULTS:
| some | thing | important |
=====
Now C-c C-c in the src block will wipe out the user-entered table!
=====
#+BEGIN_SRC emacs-lisp
(message "Hello")
#+END_SRC
#+RESULTS:
: Hello
=====
That's why I proposed earlier to wrap the Org generated results in something like #+begin_results/#+end_results.
That way, Org is always sure that what it's deleting/overwriting is not user-entered data.
The current behavior is risky, or at least should somehow be documented.