API Docs improvement

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

API Docs improvement

Maksim Ivanov
Hello all,


Several improvement suggestions for the PC/SC-Lite API documentation:

* SCardGetStatusChange: Indicate that the return code SCARD_E_CANCELLED is possible.

* SCardEstablishContext: the mentioned SCARD_SCOPE_GLOBAL value of the dwScope argument is not defined in any public header file.

* SCardStatus: There is some mess regarding whether the reader name is a multi-string or a simple string: the argument mszReaderName is sometimes referred as szReaderName; the documentation of the pcchReaderLen argument also says "multistring".

* SCardTransmit: the pioSendPci argument is marked as [in,out], while actually it's an input-only argument (it's even a pointer-to-const).

* SCardTransmit: the example code passes a pointer to uninitialized SCARD_IO_REQUEST structure as the pioRecvPci argument value - while it's an in-out argument (and the SCardTransmit implementation actually reads data from it).

* SCardListReaderGroups: It is stated that SCARD_E_INVALID_PARAMETER is returned when the mszGroups argument value is NULL, while it doesn't mention that this only happens when *pcchGroups is equal to SCARD_AUTOALLOCATE.


Regards,
Maksim

_______________________________________________
Pcsclite-muscle mailing list
[hidden email]
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pcsclite-muscle
Reply | Threaded
Open this post in threaded view
|

Re: API Docs improvement

Ludovic Rousseau

2016-03-09 18:47 GMT+01:00 Maksim Ivanov <[hidden email]>:
Hello all,

Hello Maksim,


Several improvement suggestions for the PC/SC-Lite API documentation:

* SCardGetStatusChange: Indicate that the return code SCARD_E_CANCELLED is possible.

Fixed in f590a950283ca46cb0f3e8b3a640254c61f31ff2
 

* SCardEstablishContext: the mentioned SCARD_SCOPE_GLOBAL value of the dwScope argument is not defined in any public header file.

Fixed in  a9dbb3c3ca1527228711f3e6c61fee15a1a80971


* SCardStatus: There is some mess regarding whether the reader name is a multi-string or a simple string: the argument mszReaderName is sometimes referred as szReaderName; the documentation of the pcchReaderLen argument also says "multistring".

Fixed in  2a80f615fc5084838a9c299609fa468772fae71b


* SCardTransmit: the pioSendPci argument is marked as [in,out], while actually it's an input-only argument (it's even a pointer-to-const).

Fixed in  bfc6c15ec7b5941efaa48a1c1e5ff7d2cd8b0fa4


* SCardTransmit: the example code passes a pointer to uninitialized SCARD_IO_REQUEST structure as the pioRecvPci argument value - while it's an in-out argument (and the SCardTransmit implementation actually reads data from it).

Fixed in  aed8486d13da8de4a77b620e28c617cc9cb18cd9


* SCardListReaderGroups: It is stated that SCARD_E_INVALID_PARAMETER is returned when the mszGroups argument value is NULL, while it doesn't mention that this only happens when *pcchGroups is equal to SCARD_AUTOALLOCATE.

Fixed in  43bac6981940ae3e8f05122342df6515aacb7fe8

Thanks. Great work.

--
 Dr. Ludovic Rousseau

_______________________________________________
Pcsclite-muscle mailing list
[hidden email]
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pcsclite-muscle
Reply | Threaded
Open this post in threaded view
|

Re: API Docs improvement

Maksim Ivanov
Hello Ludovic,

Thanks for the fast replies!


I additionally checked the code examples and found a couple of small issues:

* Code example for SCardCancel: the sample looks like SCardCancel is
called on the same thread as SCardGetStatusChange, which shouldn't
happen probably. Also the SCardGetStatusChange argument values are a
bit misleading: dwTimeout=0 means that no actual waiting will occur
(and, hence, no cancellation is useful), rgReaderStates receives
SCARD_READERSTATE instead of LPSCARD_READERSTATE, and
cReaders=cReaders is not initialized to 1 in the sample code.

* Code example for SCardControl: missing comma in pbSendBuffer assignment.

* Code example for SCardListReaders: missing semicolon after
assignment to dwReaders.


What else I badly missed in the PC/SC-Lite docs is the clear
description of what arguments are optional (i.e. can be NULL instead
of the real pointers). Often this follows from the textual description
of the function, or can be guessed. And in some cases this information
cannot be derived from the context at all (like pioRecvPci argument of
the SCardTransmit function).

It would be great if this information would be easily available in the
"Parameters" section of each function's description.


Regards,
Maksim


On Fri, Mar 11, 2016 at 10:34 AM, Ludovic Rousseau
<[hidden email]> wrote:

>
> 2016-03-09 18:47 GMT+01:00 Maksim Ivanov <[hidden email]>:
>>
>> Hello all,
>
>
> Hello Maksim,
>
>>
>> Several improvement suggestions for the PC/SC-Lite API documentation:
>>
>> * SCardGetStatusChange: Indicate that the return code SCARD_E_CANCELLED is
>> possible.
>
>
> Fixed in f590a950283ca46cb0f3e8b3a640254c61f31ff2
>
>>
>>
>> * SCardEstablishContext: the mentioned SCARD_SCOPE_GLOBAL value of the
>> dwScope argument is not defined in any public header file.
>
>
> Fixed in  a9dbb3c3ca1527228711f3e6c61fee15a1a80971
>
>>
>> * SCardStatus: There is some mess regarding whether the reader name is a
>> multi-string or a simple string: the argument mszReaderName is sometimes
>> referred as szReaderName; the documentation of the pcchReaderLen argument
>> also says "multistring".
>
>
> Fixed in  2a80f615fc5084838a9c299609fa468772fae71b
>
>>
>> * SCardTransmit: the pioSendPci argument is marked as [in,out], while
>> actually it's an input-only argument (it's even a pointer-to-const).
>
>
> Fixed in  bfc6c15ec7b5941efaa48a1c1e5ff7d2cd8b0fa4
>
>>
>> * SCardTransmit: the example code passes a pointer to uninitialized
>> SCARD_IO_REQUEST structure as the pioRecvPci argument value - while it's an
>> in-out argument (and the SCardTransmit implementation actually reads data
>> from it).
>
>
> Fixed in  aed8486d13da8de4a77b620e28c617cc9cb18cd9
>
>>
>> * SCardListReaderGroups: It is stated that SCARD_E_INVALID_PARAMETER is
>> returned when the mszGroups argument value is NULL, while it doesn't mention
>> that this only happens when *pcchGroups is equal to SCARD_AUTOALLOCATE.
>
>
> Fixed in  43bac6981940ae3e8f05122342df6515aacb7fe8
>
> Thanks. Great work.
>
> --
>  Dr. Ludovic Rousseau
>
> _______________________________________________
> Pcsclite-muscle mailing list
> [hidden email]
> http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pcsclite-muscle


Maksim Ivanov

Software Engineer

[hidden email]
+49 (0)176 65889070

Google Germany GmbH

Dienerstraße 12

80331 München


Geschäftsführer: Matthew Scott Sucherman, Paul Terence Manicle

Registergericht und -nummer: Hamburg, HRB 86891

Sitz der Gesellschaft: Hamburg


Diese E-Mail ist vertraulich. Wenn Sie nicht der richtige Adressat
sind, leiten Sie diese bitte nicht weiter, informieren Sie den
Absender und löschen Sie die E-Mail und alle Anhänge. Vielen Dank.



This e-mail is confidential. If you are not the right addressee please
do not forward it, please inform the sender, and please erase this
e-mail including any attachments. Thanks.

_______________________________________________
Pcsclite-muscle mailing list
[hidden email]
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pcsclite-muscle
Reply | Threaded
Open this post in threaded view
|

Re: API Docs improvement

Ludovic Rousseau


2016-03-11 14:46 GMT+01:00 Maksim Ivanov <[hidden email]>:
Hello Ludovic,

Thanks for the fast replies!


I additionally checked the code examples and found a couple of small issues:

* Code example for SCardCancel: the sample looks like SCardCancel is
called on the same thread as SCardGetStatusChange, which shouldn't
happen probably. Also the SCardGetStatusChange argument values are a
bit misleading: dwTimeout=0 means that no actual waiting will occur
(and, hence, no cancellation is useful), rgReaderStates receives
SCARD_READERSTATE instead of LPSCARD_READERSTATE, and
cReaders=cReaders is not initialized to 1 in the sample code.

* Code example for SCardControl: missing comma in pbSendBuffer assignment.

* Code example for SCardListReaders: missing semicolon after
assignment to dwReaders.


Fixed in  6cd24b9c83513c207cff39afbf9b653cbf8d004a

A better solution would be to include real/compilable code in Doxygen.


What else I badly missed in the PC/SC-Lite docs is the clear
description of what arguments are optional (i.e. can be NULL instead
of the real pointers). Often this follows from the textual description
of the function, or can be guessed. And in some cases this information
cannot be derived from the context at all (like pioRecvPci argument of
the SCardTransmit function).

It would be great if this information would be easily available in the
"Parameters" section of each function's description.

Good idea.

Bye

--
 Dr. Ludovic Rousseau

_______________________________________________
Pcsclite-muscle mailing list
[hidden email]
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pcsclite-muscle