<html><body><div style="color:#000; background-color:#fff; font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:10pt"><div style="display: block;" class="yahoo_quoted">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<br><div style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 10pt;"> <div style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 12pt;"> <div dir="ltr"> <font face="Arial" size="2"> On Sunday, March 30, 2014 12:49 PM, Marco Antoniotti <marcoxa@cs.nyu.edu> wrote:<br> </font> </div> <blockquote style="border-left: 2px solid rgb(16, 16, 255);
margin-left: 5px; margin-top: 5px; padding-left: 5px;"> <div class="y_msg_container"><div id="yiv5059870647"><div><br clear="none">On Mar 30, 2014, at 20:26 , Joeish W <<a rel="nofollow" shape="rect" ymailto="mailto:joeish80829@yahoo.com" target="_blank" href="mailto:joeish80829@yahoo.com">joeish80829@yahoo.com</a>> wrote:<br clear="none"><br clear="none"><blockquote type="cite">Here is the definition, but thanks for the HELambdaP idea<br clear="none">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.<br clear="none"><br clear="none">;; double RNG::uniform(double a, double b) ;; C++<br clear="none">;; double cv_RNG_uniform_double(RNG* self, double a, double b) ;; C <br clear="none">(defcfun ("cv_RNG_uniform_double" uniform-d) :double <br clear="none"> "Returns the next random number sampled from the uniform
distribution." <br clear="none"> (self (:pointer rng)) <br clear="none"> (a :double) <br clear="none"> (b :double))<br clear="none"></blockquote><div><br clear="none"></div><div><br clear="none"></div><div>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.</div><div><br clear="none"></div><div>I first stab (untested) could be</div><div><br clear="none"></div><div><font face="Courier New">(in-package “HELAMBDA”)</font></div><div><font face="Courier New"><br clear="none"></font></div><div><font face="Courier New">(defstruct (cffi-cfun-doc-bit (:include function-doc-bit (kind-tag “C Function”)))</font></div><div><font face="Courier New"> (c-name "" :read-only t :type string)</font></div><div><font face="Courier New"> (cffi-argument-types () :read-only t :type list))</font></div><div><font
face="Courier New"><br clear="none"></font></div><div><font face="Courier New"><br clear="none"></font></div><div><font face="Courier New">(defmethod extract-form-documentation ((fk (eql 'cffi:defcfun)) (form cons))</font></div><div><font face="Courier New"> (destructuring-bind (defcfun name-and-options return-type &rest spec)</font></div><div><font face="Courier New"> form</font></div><div><font face="Courier New"> (declare (ignore defcfun))</font></div><div><font face="Courier New"> (let ((name (munge-name-and-option-for-name name-and-options))</font></div><div><div><font face="Courier New"> (c-name (munge-name-and-option-for-c-name name-and-options))</font></div></div><div><font face="Courier New"> )</font></div><div><font face="Courier New"> (make-cffi-cfun-doc-bit</font></div><div><font face="Courier New">
:name name</font></div><div><font face="Courier New"> :c-name c-name</font></div><div><font face="Courier New"> :lambda-list (mapcar #’first (spec-sans-docstring spec))</font></div><div><font face="Courier New"> :doc-string (if (stringp (first spec)) (first spec))</font></div><div><font face="Courier New"> :values return-type</font></div><div><font face="Courier New"> :cffi-argument-types (munge-cffi-spec spec)</font></div><div><font face="Courier New"> #| other keys here … |#</font></div><div><font face="Courier New"> )))</font></div><div><font face="Courier New"> </font></div><div><font face="Courier New"> </font></div><div>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:</div><div><br clear="none"></div><div><font face="Verdana"><b><i>Function</i> uniform-d</b></font></div><div><font face="Verdana"><b><br clear="none"></b></font></div><div><font face="Verdana"><b>Package:</b></font></div><div><font face="Verdana"><br clear="none"></font></div><div><font face="Courier New">CV_RNG</font></div><div><font face="Verdana"><br clear="none"></font></div><div><font face="Verdana"><b>Syntax:</b></font></div><div><font face="Verdana"><br clear="none"></font></div><div><font face="Courier New"><b>uniform-d</b> self a b</font></div><div><font face="Verdana"><br clear="none"></font></div><div><font face="Verdana"><b>Arguments and Values:</b></font></div><div><font face="Verdana"><br clear="none"></font></div><div><font face="Verdana">SELF : a T</font></div><div><font face="Verdana">A : a T</font></div><div><font
face="Verdana">B : a T</font></div><div><font face="Verdana">RESULT : a T</font></div><div><font face="Verdana"><br clear="none"></font></div><div><font face="Verdana"><b>Description:</b></font></div><div><font face="Verdana"><br clear="none"></font></div><div><div><font face="Verdana">Returns the next random number sampled from the uniform distribution.</font></div></div><div><br clear="none"></div><div>If your doc string were the following:</div><div><br clear="none"></div><div><font face="Courier New">"Returns the next random number sampled from the uniform distribution.</font></div><div><font face="Courier New"><br clear="none"></font></div><div><font face="Courier New">Arguments and Values:</font></div><div><font face="Courier New"><br clear="none"></font></div><div><font face="Courier New">SELF : a pointer to a RNG</font></div><div><font face="Courier New">A : a DOUBLE</font></div><div><font face="Courier New">B : a DOUBLE</font></div><div><font
face="Courier New">RESULT : a DOUBLE</font></div><div><font face="Courier New">"</font></div><div>then the “Arguments and Values:” section would be copied as is (more or less).</div><div><br clear="none"></div><div><br clear="none"></div><div>Of course, you could define a specialized method to produce the DEFCFUN documentation.</div><div><br clear="none"></div><div><font face="Courier New">(defmethod produce-documentation ((format (eql 'html))</font></div><div><font face="Courier New"> (doc-bit cffi-cfun-doc-bit)</font></div><div><font face="Courier New"> (out file-stream)</font></div><div><font face="Courier New">
doc-bits</font></div><div><font face="Courier New"> &key</font></div><div><font face="Courier New"> documentation-title</font></div><div><font face="Courier New"> &allow-other-keys)</font></div><div><font face="Courier New"> #| … |#</font></div><div><font face="Courier New"> )</font></div><div><br clear="none"></div><div><br clear="none"></div><div><br clear="none"></div><div>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 :)</div><div><br clear="none"></div><div>Cheers</div><div>—</div><div>MA</div><div><br clear="none"></div><div><br clear="none"></div><div><br clear="none"></div><br clear="none"><blockquote type="cite">On Sunday, March 30, 2014 9:44 AM, Marco Antoniotti <<a rel="nofollow" shape="rect" ymailto="mailto:marcoxa@cs.nyu.edu" target="_blank" href="mailto:marcoxa@cs.nyu.edu">marcoxa@cs.nyu.edu</a>> wrote:<br clear="none">What is the CFFI actual definition?<br clear="none"><br clear="none">I - but that is a very selfish proposal :) - would just write a proper handler for HELambdaP.<br clear="none"><br clear="none">Cheers<br clear="none"><br clear="none">MA<br clear="none"><br clear="none"><br clear="none"><br clear="none"><br clear="none"><br clear="none">On Mar 30, 2014, at 17:11 , Joeish W <<a rel="nofollow" shape="rect" ymailto="mailto:joeish80829@yahoo.com" target="_blank"
href="mailto:joeish80829@yahoo.com">joeish80829@yahoo.com</a>> wrote:<br clear="none"><br clear="none">> Which is the better way do write documentation for functions for a CFFI library<br clear="none">> <br clear="none">> like this?<br clear="none">> <br clear="none">> C++: int RNG::uniform(int a, int b)<br clear="none">> <br clear="none">> Common Lisp: (UNIFORM-D (RNG (:POINTER RNG)) (A :DOUBLE) (B :DOUBLE)) => :DOUBLE<br clear="none">> <br clear="none">> or like this without the parenthesis<br clear="none">> <br clear="none">> C++: float RNG::uniform(float a, float b)<br clear="none">> <br clear="none">> Common Lisp: (UNIFORM-F (RNG :POINTER RNG) A :FLOAT B :FLOAT) => :FLOAT<br clear="none">> <br clear="none">> _______________________________________________<br clear="none">> Cffi-devel mailing list<br
clear="none">> Cffi-devel@common-lisp.net<br clear="none">> http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel<br clear="none"><br clear="none">--<br clear="none">Marco Antoniotti<br clear="none"><br clear="none"><br clear="none"><br clear="none"><br clear="none">_______________________________________________<br clear="none">Cffi-devel mailing list<br clear="none">Cffi-devel@common-lisp.net<br clear="none">http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel<div class="yiv5059870647yqt3392529750" id="yiv5059870647yqtfd28735"><br clear="none"><br clear="none"><br clear="none">_______________________________________________<br clear="none">Cffi-devel mailing list<br clear="none">Cffi-devel@common-lisp.net<br clear="none">http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel<br clear="none"></div></blockquote><div class="yiv5059870647yqt3392529750" id="yiv5059870647yqtfd91027"><br clear="none"><div>--<br
clear="none">Marco Antoniotti<br clear="none"><br clear="none"></div><br clear="none"></div></div></div><br><div class="yqt3392529750" id="yqtfd67036">_______________________________________________<br clear="none">Cffi-devel mailing list<br clear="none"><a shape="rect" ymailto="mailto:Cffi-devel@common-lisp.net" href="mailto:Cffi-devel@common-lisp.net">Cffi-devel@common-lisp.net</a><br clear="none"><a shape="rect" href="http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel" target="_blank">http://common-lisp.net/cgi-bin/mailman/listinfo/cffi-devel</a><br clear="none"></div><br><br></div> </blockquote> </div> </div> </div> </div></body></html>