RFC: OpenCT driver API documentation

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

RFC: OpenCT driver API documentation

Laurent Pinchart
Hi everybody,

I spent some time trying to understand the OpenCT driver API (interface
between OpenCT and the ifd-* drivers), so I thought I could as well document
it. You'll find a first documentation draft attached to this e-mail. The
functions I wasn't sure of were marked as such, please help me to undertand
them and tell me where I made mistakes.

Laurent Pinchart

_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel

driver-api (11K) Download Attachment
attachment1 (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation [u]

Andreas Jellinghaus-2
Hi Laurent,

wow, thanks for writing this documentation. great!
How shall we add this to openct? as text file? or
put it in the wiki? I'm also considering javadoc
style comments and doxygen, but I have no experience with
that so far. What is your preference?

Andreas
p.s. I saw your questions but I don't know those parts of
the code any better. Need to find time to carefully read
the code so I can help with them.
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation

Ludovic Rousseau
In reply to this post by Laurent Pinchart
On 05/08/05, Laurent Pinchart <[hidden email]> wrote:
> Hi everybody,

Hello,
 
> I spent some time trying to understand the OpenCT driver API (interface
> between OpenCT and the ifd-* drivers), so I thought I could as well document
> it. You'll find a first documentation draft attached to this e-mail. The
> functions I wasn't sure of were marked as such, please help me to undertand
> them and tell me where I made mistakes.

Nice job.

Maybe this should be integrated in the source code as a Doxygen [1]
documentation to:
- not lose this work
- keep it in sync if ever the API change (it is easy to update the doc
at the same time the API is changed if they are in the same file)
- generate nice HTML pages

I propose to put it in src/include/openct/driver.h

Laurent, do you volunteer for this task?

Regards,

[1] http://www.stack.nl/~dimitri/doxygen/

--
 Dr. Ludovic Rousseau
 For private mail use [hidden email] and not "big brother" Google
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation

Laurent Pinchart
Hi,

> Nice job.

Thanks

> Maybe this should be integrated in the source code as a Doxygen [1]
> documentation to:
> - not lose this work
> - keep it in sync if ever the API change (it is easy to update the doc
> at the same time the API is changed if they are in the same file)
> - generate nice HTML pages
>
> I propose to put it in src/include/openct/driver.h
>
> Laurent, do you volunteer for this task?
I do. Do you have any preference for javadoc-style or qt-style format ?

Javadoc:

/**
 * @param
 */

Qt:

/*!
 * \param
 */

I will need answers to the few questions left in my last e-mail to fill in the
last gaps.

Laurent Pinchart

_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel

attachment0 (196 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation

Ludovic Rousseau
On 08/08/05, Laurent Pinchart <[hidden email]> wrote:
> > Laurent, do you volunteer for this task?
>
> I do. Do you have any preference for javadoc-style or qt-style format ?

javadoc is fine for me. Andreas also agree regarding his answer.

> I will need answers to the few questions left in my last e-mail to fill in the
> last gaps.

I can't help you here. I do not know or use OpenCT.

Bye,

--
 Dr. Ludovic Rousseau
 For private mail use [hidden email] and not "big brother" Google
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation [u]

Andreas Jellinghaus-2
In reply to this post by Laurent Pinchart
Hi, I still don't know how to properly use doxygen,
so to make sure Laurents documentation is not lost I
added it to the wiki.

Andreas
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation [u]

Douglas de Oliveira Mendes-2
    Here's an example of how to write the documentation:

/**
 * Authenticates with the card.
 * @param slot The slot where the token is.
 * @param so Wether login as SO or not.
 * @param pin The pin needed to gain card access.
 * @return -1 if already logged in or if couldn't open a session, 0 if
logged in successfully.
 */
int PKCS11_login(PKCS11_SLOT * slot, int so, const char *pin)

Is that some help?
Douglas

Andreas Jellinghaus [c] escreveu:

>Hi, I still don't know how to properly use doxygen,
>so to make sure Laurents documentation is not lost I
>added it to the wiki.
>
>Andreas
>_______________________________________________
>opensc-devel mailing list
>[hidden email]
>http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
>
>  
>

       

       
               
_______________________________________________________
Novo Yahoo! Messenger com voz: liga??es, Yahoo! Avatars, novos emoticons e muito mais. Instale agora!
www.yahoo.com.br/messenger/
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation [u]

Douglas de Oliveira Mendes-2
In reply to this post by Andreas Jellinghaus-2
    Err.. that's an example for libp11 and not openct, of course.. :-P

Douglas


       

       
               
_______________________________________________________
Novo Yahoo! Messenger com voz: liga??es, Yahoo! Avatars, novos emoticons e muito mais. Instale agora!
www.yahoo.com.br/messenger/
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation

Andreas Jellinghaus-2
In reply to this post by Douglas de Oliveira Mendes-2
On Thursday 22 September 2005 23:10, Douglas de Oliveira Mendes wrote:

>     Here's an example of how to write the documentation:
>
> /**
>  * Authenticates with the card.
>  * @param slot The slot where the token is.
>  * @param so Wether login as SO or not.
>  * @param pin The pin needed to gain card access.
>  * @return -1 if already logged in or if couldn't open a session, 0 if
> logged in successfully.
>  */
> int PKCS11_login(PKCS11_SLOT * slot, int so, const char *pin)
>
> Is that some help?

yes, thanks a lot.

now that opensc 0.10.0-beta1 is out of the door I can go back
to those issues.

Andreas
p.s. unless big bugs are found :)
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: RFC: OpenCT driver API documentation [u]

Nils Larsch
In reply to this post by Douglas de Oliveira Mendes-2
Douglas de Oliveira Mendes wrote:

>     Here's an example of how to write the documentation:
>
> /**
>  * Authenticates with the card.
>  * @param slot The slot where the token is.
>  * @param so Wether login as SO or not.
>  * @param pin The pin needed to gain card access.
>  * @return -1 if already logged in or if couldn't open a session, 0 if
> logged in successfully.
>  */
> int PKCS11_login(PKCS11_SLOT * slot, int so, const char *pin)

to improve readability I would suggest adding some extra whitespaces
so that all parameters form one column (and add a extra whitespace
between the parameters in @param and the description), i.e. in your
example.

/**
  * Authenticates with the card.
  * @param  slot  The slot where the token is.
  * @param  so    Wether login as SO or not.
  * @param  pin   The pin needed to gain card access.
  * @return -1 if already logged in or if couldn't open a session, 0 if
  *         logged in successfully.
  */
int PKCS11_login(PKCS11_SLOT * slot, int so, const char *pin)

last week I've added some doxygen comments to openssl (see [1]) and
I think ordering the comments in a table really helps if you want
to read the header file.

Cheers,
Nils
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel