[Cffi-devel] Fw: writing documentation for CFFI functions

[Joeish W]

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 at cs.nyu.edu> wrote:
 

>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
>
>
>
>
>_______________________________________________
>Cffi-devel mailing list
>Cffi-devel at common-lisp.net
>http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/cffi-devel/attachments/20140330/a0f20974/attachment.html>