[Cffi-devel] writing documentation for CFFI functions

[Marco Antoniotti]

On Mar 30, 2014, at 20:26 , Joeish W <joeish80829 at 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 at 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 at 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 at common-lisp.net
> > http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
> 
> --
> Marco Antoniotti
> 
> 
> 
> 
> _______________________________________________
> Cffi-devel mailing list
> Cffi-devel at common-lisp.net
> http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
> 
> 
> _______________________________________________
> Cffi-devel mailing list
> Cffi-devel at common-lisp.net
> http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel

--
Marco Antoniotti


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/cffi-devel/attachments/20140330/330e46df/attachment.html>