[Cffi-devel] writing documentation for CFFI functions
Which is the better way do write documentation for functions for a CFFI library like this? C++: int RNG::uniform(int a, int b) Common Lisp: (UNIFORM-D (RNG (:POINTER RNG)) (A :DOUBLE) (B :DOUBLE)) => :DOUBLE or like this without the parenthesis C++: float RNG::uniform(float a, float b) Common Lisp: (UNIFORM-F (RNG :POINTER RNG) A :FLOAT B :FLOAT) => :FLOAT
What is the CFFI actual definition? I - but that is a very selfish proposal :) - would just write a proper handler for HELambdaP. Cheers MA On Mar 30, 2014, at 17:11 , Joeish W <joeish80829@yahoo.com> wrote:
Which is the better way do write documentation for functions for a CFFI library
like this?
C++: int RNG::uniform(int a, int b)
Common Lisp: (UNIFORM-D (RNG (:POINTER RNG)) (A :DOUBLE) (B :DOUBLE)) => :DOUBLE
or like this without the parenthesis
C++: float RNG::uniform(float a, float b)
Common Lisp: (UNIFORM-F (RNG :POINTER RNG) A :FLOAT B :FLOAT) => :FLOAT
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
-- Marco Antoniotti
Here is the definition, but thanks for the HELambdaP idea Trust me the opinion of a CFFI expert does matter...could you also show me what a HELambdaP definition would look like for this defcfun. ;; double RNG::uniform(double a, double b) ;; C++ ;; double cv_RNG_uniform_double(RNG* self, double a, double b) ;; C (defcfun ("cv_RNG_uniform_double" uniform-d) :double "Returns the next random number sampled from the uniform distribution." (self (:pointer rng)) (a :double) (b :double)) On Sunday, March 30, 2014 9:44 AM, Marco Antoniotti <marcoxa@cs.nyu.edu> wrote: What is the CFFI actual definition?
I - but that is a very selfish proposal :) - would just write a proper handler for HELambdaP.
Cheers
MA
On Mar 30, 2014, at 17:11 , Joeish W <joeish80829@yahoo.com> wrote:
Which is the better way do write documentation for functions for a CFFI library
like this?
C++: int RNG::uniform(int a, int b)
Common Lisp: (UNIFORM-D (RNG (:POINTER RNG)) (A :DOUBLE) (B :DOUBLE)) => :DOUBLE
or like this without the parenthesis
C++: float RNG::uniform(float a, float b)
Common Lisp: (UNIFORM-F (RNG :POINTER RNG) A :FLOAT B :FLOAT) => :FLOAT
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
-- Marco Antoniotti
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
On Mar 30, 2014, at 20:26 , Joeish W <joeish80829@yahoo.com> wrote:
Here is the definition, but thanks for the HELambdaP idea Trust me the opinion of a CFFI expert does matter...could you also show me what a HELambdaP definition would look like for this defcfun.
;; double RNG::uniform(double a, double b) ;; C++ ;; double cv_RNG_uniform_double(RNG* self, double a, double b) ;; C (defcfun ("cv_RNG_uniform_double" uniform-d) :double "Returns the next random number sampled from the uniform distribution." (self (:pointer rng)) (a :double) (b :double))
What you need is to define (I can actually define it for a next release) a specialized DOC-BIT for CFFI “cfun”s and a EXTRACT-FORM-DOCUMENTATION method. I first stab (untested) could be (in-package “HELAMBDA”) (defstruct (cffi-cfun-doc-bit (:include function-doc-bit (kind-tag “C Function”))) (c-name "" :read-only t :type string) (cffi-argument-types () :read-only t :type list)) (defmethod extract-form-documentation ((fk (eql 'cffi:defcfun)) (form cons)) (destructuring-bind (defcfun name-and-options return-type &rest spec) form (declare (ignore defcfun)) (let ((name (munge-name-and-option-for-name name-and-options)) (c-name (munge-name-and-option-for-c-name name-and-options)) ) (make-cffi-cfun-doc-bit :name name :c-name c-name :lambda-list (mapcar #’first (spec-sans-docstring spec)) :doc-string (if (stringp (first spec)) (first spec)) :values return-type :cffi-argument-types (munge-cffi-spec spec) #| other keys here … |# ))) Note that the missing functions are needed to munge the DEFCFUN encoded information. At this point, from your example, HELAMBDAP will happily produce a documentation like the following: Function uniform-d Package: CV_RNG Syntax: uniform-d self a b Arguments and Values: SELF : a T A : a T B : a T RESULT : a T Description: Returns the next random number sampled from the uniform distribution. If your doc string were the following: "Returns the next random number sampled from the uniform distribution. Arguments and Values: SELF : a pointer to a RNG A : a DOUBLE B : a DOUBLE RESULT : a DOUBLE " then the “Arguments and Values:” section would be copied as is (more or less). Of course, you could define a specialized method to produce the DEFCFUN documentation. (defmethod produce-documentation ((format (eql 'html)) (doc-bit cffi-cfun-doc-bit) (out file-stream) doc-bits &key documentation-title &allow-other-keys) #| … |# ) Of course, YMMV… As I said, I will be very happy to provide a HELambdaP extension for CFFI. Actually, let me rephrase it: I will be happy to coordinate a HELambdaP extension for CFFI :) Cheers — MA
On Sunday, March 30, 2014 9:44 AM, Marco Antoniotti <marcoxa@cs.nyu.edu> wrote: What is the CFFI actual definition?
I - but that is a very selfish proposal :) - would just write a proper handler for HELambdaP.
Cheers
MA
On Mar 30, 2014, at 17:11 , Joeish W <joeish80829@yahoo.com> wrote:
Which is the better way do write documentation for functions for a CFFI library
like this?
C++: int RNG::uniform(int a, int b)
Common Lisp: (UNIFORM-D (RNG (:POINTER RNG)) (A :DOUBLE) (B :DOUBLE)) => :DOUBLE
or like this without the parenthesis
C++: float RNG::uniform(float a, float b)
Common Lisp: (UNIFORM-F (RNG :POINTER RNG) A :FLOAT B :FLOAT) => :FLOAT
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
-- Marco Antoniotti
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
-- Marco Antoniotti
Thanks ...I was wondering what my documentation would like like if done by a documentation tool, I appreciate that..So do you think what I was doing so far was pretty confusing/would be confusiong to other people...I had not really seen any CFFI code documentation so I just winged it On Sunday, March 30, 2014 12:49 PM, Marco Antoniotti <marcoxa@cs.nyu.edu> wrote:
On Mar 30, 2014, at 20:26 , Joeish W <joeish80829@yahoo.com> wrote:
Here is the definition, but thanks for the HELambdaP idea
Trust me the opinion of a CFFI expert does matter...could you also show me what a HELambdaP definition would look like for this defcfun.
;; double RNG::uniform(double a, double b) ;; C++ ;; double cv_RNG_uniform_double(RNG* self, double a, double b) ;; C (defcfun ("cv_RNG_uniform_double" uniform-d) :double "Returns the next random number sampled from the uniform distribution." (self (:pointer rng)) (a :double) (b :double))
What you need is to define (I can actually define it for a next release) a specialized DOC-BIT for CFFI “cfun”s and a EXTRACT-FORM-DOCUMENTATION method.
I first stab (untested) could be
(in-package “HELAMBDA”)
(defstruct (cffi-cfun-doc-bit (:include function-doc-bit (kind-tag “C Function”))) (c-name "" :read-only t :type string) (cffi-argument-types () :read-only t :type list))
(defmethod extract-form-documentation ((fk (eql 'cffi:defcfun)) (form cons)) (destructuring-bind (defcfun name-and-options return-type &rest spec) form (declare (ignore defcfun)) (let ((name (munge-name-and-option-for-name name-and-options)) (c-name (munge-name-and-option-for-c-name name-and-options)) ) (make-cffi-cfun-doc-bit :name name :c-name c-name :lambda-list (mapcar #’first (spec-sans-docstring spec)) :doc-string (if (stringp (first spec)) (first spec)) :values return-type :cffi-argument-types (munge-cffi-spec spec) #| other keys here … |# ))) Note that the missing functions are needed to munge the DEFCFUN encoded information. At this point, from your example, HELAMBDAP will happily produce a documentation like the following:
Function uniform-d
Package:
CV_RNG
Syntax:
uniform-d self a b
Arguments and Values:
SELF : a T A : a T B : a T RESULT : a T
Description:
Returns the next random number sampled from the uniform distribution.
If your doc string were the following:
"Returns the next random number sampled from the uniform distribution.
Arguments and Values:
SELF : a pointer to a RNG A : a DOUBLE B : a DOUBLE RESULT : a DOUBLE " then the “Arguments and Values:” section would be copied as is (more or less).
Of course, you could define a specialized method to produce the DEFCFUN documentation.
(defmethod produce-documentation ((format (eql 'html)) (doc-bit cffi-cfun-doc-bit) (out file-stream) doc-bits &key documentation-title &allow-other-keys) #| … |# )
Of course, YMMV… As I said, I will be very happy to provide a HELambdaP extension for CFFI. Actually, let me rephrase it: I will be happy to coordinate a HELambdaP extension for CFFI :)
Cheers — MA
On Sunday, March 30, 2014 9:44 AM, Marco Antoniotti <marcoxa@cs.nyu.edu> wrote:
What is the CFFI actual definition?
I - but that is a very selfish proposal :) - would just write a proper handler for HELambdaP.
Cheers
MA
On Mar 30, 2014, at 17:11 , Joeish W <joeish80829@yahoo.com> wrote:
Which is the better way do write documentation for functions for a CFFI library like this? C++: int RNG::uniform(int a, int b) Common Lisp: (UNIFORM-D (RNG (:POINTER RNG)) (A :DOUBLE) (B :DOUBLE)) => :DOUBLE or like this without the parenthesis C++: float RNG::uniform(float a, float b) Common Lisp: (UNIFORM-F (RNG :POINTER RNG) A :FLOAT B :FLOAT) => :FLOAT _______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
-- Marco Antoniotti
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
-- Marco Antoniotti
_______________________________________________ Cffi-devel mailing list Cffi-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
participants (2)
-
Joeish W -
Marco Antoniotti