From 8e2f6d94e95e15a35295105ba82f41ba05401507 Mon Sep 17 00:00:00 2001 From: Ihor Radchenko Date: Wed, 2 Aug 2023 10:42:39 +0300 Subject: [PATCH] ob-C: Fix docstrings * lisp/ob-C.el (org-babel-execute:cpp): (org-babel-expand-body:cpp): (org-babel-execute:C++): (org-babel-expand-body:C++): (org-babel-execute:D): (org-babel-expand-body:D): (org-babel-execute:C): (org-babel-expand-body:C): (org-babel-C-execute): (org-babel-C-expand-C++): (org-babel-C-expand-C): (org-babel-C-expand-D): (org-babel-C-val-to-base-type): (org-babel-C-var-to-C): Mention all the arguments. (org-babel-prep-session:C): (org-babel-load-session:C): Make first line a proper short description consisting of a single sentence. --- lisp/ob-C.el | 48 ++++++++++++++++++++++++++---------------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/lisp/ob-C.el b/lisp/ob-C.el index 7763c4c07..9a24c079e 100644 --- a/lisp/ob-C.el +++ b/lisp/ob-C.el @@ -93,44 +93,45 @@ parameter may be used, like rdmd --chatty" is currently being evaluated.") (defun org-babel-execute:cpp (body params) - "Execute BODY according to PARAMS. + "Execute BODY according to its header arguments PARAMS. This function calls `org-babel-execute:C++'." (org-babel-execute:C++ body params)) (defun org-babel-expand-body:cpp (body params) - "Expand a block of C++ code with org-babel according to its header arguments." + "Expand C++ BODY with org-babel according to its header arguments PARAMS." (org-babel-expand-body:C++ body params)) (defun org-babel-execute:C++ (body params) - "Execute a block of C++ code with org-babel. + "Execute C++ BODY with org-babel according to its header arguments PARAMS. This function is called by `org-babel-execute-src-block'." (let ((org-babel-c-variant 'cpp)) (org-babel-C-execute body params))) (defun org-babel-expand-body:C++ (body params) - "Expand a block of C++ code with org-babel according to its header arguments." + "Expand C++ BODY with org-babel according to its header arguments PARAMS." (let ((org-babel-c-variant 'cpp)) (org-babel-C-expand-C++ body params))) (defun org-babel-execute:D (body params) - "Execute a block of D code with org-babel. + "Execute D BODY with org-babel according to its header arguments PARAMS. This function is called by `org-babel-execute-src-block'." (let ((org-babel-c-variant 'd)) (org-babel-C-execute body params))) (defun org-babel-expand-body:D (body params) - "Expand a block of D code with org-babel according to its header arguments." + "Expand D BODY with org-babel according to its header arguments PARAMS." (let ((org-babel-c-variant 'd)) (org-babel-C-expand-D body params))) (defun org-babel-execute:C (body params) - "Execute a block of C code with org-babel. + "Execute a C BODY according to its header arguments PARAMS. This function is called by `org-babel-execute-src-block'." (let ((org-babel-c-variant 'c)) (org-babel-C-execute body params))) (defun org-babel-expand-body:C (body params) - "Expand a block of C code with org-babel according to its header arguments." + "Expand C BODY according to its header arguments PARAMS." (let ((org-babel-c-variant 'c)) (org-babel-C-expand-C body params))) (defun org-babel-C-execute (body params) - "This function should only be called by `org-babel-execute:C' -or `org-babel-execute:C++' or `org-babel-execute:D'." + "Execute C/C++/D BODY according to its header arguments PARAMS. +This function should only be called by `org-babel-execute:C' or +`org-babel-execute:C++' or `org-babel-execute:D'." (let* ((tmp-src-file (org-babel-temp-file "C-src-" (pcase org-babel-c-variant @@ -196,11 +197,11 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." ))) (defun org-babel-C-expand-C++ (body params) - "Expand a block of C/C++ code with org-babel according to its header arguments." + "Expand C/C++ BODY with according to its header arguments PARAMS." (org-babel-C-expand-C body params)) (defun org-babel-C-expand-C (body params) - "Expand a block of C/C++ code with org-babel according to its header arguments." + "Expand C/C++ BODY according to its header arguments PARAMS." (let ((vars (org-babel--get-vars params)) (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) @@ -269,7 +270,7 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." body) "\n") "\n"))) (defun org-babel-C-expand-D (body params) - "Expand a block of D code with org-babel according to its header arguments." + "Expand D BODY according to its header arguments PARAMS." (let ((vars (org-babel--get-vars params)) (colnames (cdr (assq :colname-names params))) (main-p (not (string= (cdr (assq :main params)) "no"))) @@ -313,13 +314,15 @@ or `org-babel-execute:C++' or `org-babel-execute:D'." (format "int main() {\n%s\nreturn 0;\n}\n" body))) (defun org-babel-prep-session:C (_session _params) - "This function does nothing as C is a compiled language with no -support for sessions." + "Throw and error that sessions are not supported. +This function does nothing as C is a compiled language with no support +for sessions." (error "C is a compiled language -- no support for sessions")) (defun org-babel-load-session:C (_session _body _params) - "This function does nothing as C is a compiled language with no -support for sessions." + "Throw and error that sessions are not supported. +This function does nothing as C is a compiled language with no support +for sessions." (error "C is a compiled language -- no support for sessions")) ;; helper functions @@ -379,10 +382,11 @@ FORMAT can be either a format string or a function which is called with VAL." type)))) (defun org-babel-C-val-to-base-type (val) - "Determine the base type of VAL which may be -`integerp' if all base values are integers -`floatp' if all base values are either floating points or integers -`stringp' otherwise." + "Determine the base type of VAL. +The type is: +- `integerp' if all base values are integers; +- `floatp' if all base values are either floating points or integers; +- `stringp' otherwise." (cond ((integerp val) 'integerp) ((floatp val) 'floatp) @@ -401,7 +405,7 @@ FORMAT can be either a format string or a function which is called with VAL." (t 'stringp))) (defun org-babel-C-var-to-C (pair) - "Convert an elisp val into a string of C code specifying a var of the same value." + "Convert PAIR of (var . val) C variable assignment." ;; TODO list support (let ((var (car pair)) (val (cdr pair)))