Hello,
On Jan 24, 2011, at 3:17 PM, jons...@terra.es wrote:
> > Not that I would want to suggest a "8 meters requirement" [1], something
> > should be done about it.
> [...]
>
> I agree:
>
> In the writting of Spanish DNIe LGPL driver I've found so many times that
> lack of information.
> A simple tutorial for writting card drivers, An overview of what iso7816.c
> does, differences
> between sc_xxx functions an their counterpart iso_xxx functions,
> how sc_transmit_apdu handle 61xx status response,
> how an when issue apdu->{resp,resplen,le} and what should be expected....
sc_ functions should be "libopensc" level functions, which already use any card
specific implementations in card-XXX.c and eventually be exported to users of
libopensc. iso7816_* is a reference base driver that should be based on
ISO-7816-X (but not necessarily feature-complete or set in stone in that
matter). Overall documentation and extra conditions and restrictions could be
noted in comments as well (reading the full specs can be time consuming and
lead to "interpretation errors").
> At this moment, I'have cwa14890 Secure Messaging working for DNIe,
> but I'm next to !wrap and rewrite! sc_transmit apdu()... because I _really_
> doesn't
> know the exact way of handling a correct get_response() (required on every SM
> apdu message)
> cmd when expected data length is not known in advance or when a previous
> function is already
> waiting for a response in their apdu
>
> So I really (really!) need a documented API and description on what is
> expected for each routine
> Perhaps not indeed to make a public API ( opensc-devel ), just a short of
> "Developer's guide"
> [...]
You can start by adding doxygen docs to the common functions and raising a flag
when there are questions or doubts. You can do that directly to trunk if you
want.
> > Overall, the goal would be to increase the effort needed to figure out
> > "how?"
> > to code right now (not just write code but do some research and refactoring
> > if necessary) and reduce the time needed later to figure out "why?"
> > certain source code exists.
> [...]
>
> My DNIe code [1] already follows Doxigen conventions. Comments/total line
> ratio is greater
> than 20%. I'm also writting a development diary[2]... Well, my SVN commit
> comments
> perhaps should be improved :-)
Nice example of doxygen in that case :)
You could as well write missing comments for internal OpenSC functions that you
don't fully understand or where you have clarified the "designed purpose".
> About rewrittng and commenting... well, revise every files on Opensc may
> lead unpractical,
> and would be better for us to (re)write wiki documentation.Not sure
I don't mean re-working all OpenSC source (which would, of course, be good) but
making sure that all code that gets touched by new commits go through the hands
of someone who makes sure that the essential amount of documentation is
available. For example, if there was a patch review system on
opensc-project.org, it could have an additional state "needs comments". What I
had in mind was that somebody else writes the documentation, if missing in
commits done by somebody else. This double check guarantees that the commit can
be interpreted on a reasonable level by at least one other person. This would
require some staging are or really great merging capabilities (better in git
than svn).
--
@MartinPaljak.net
+3725156495
_______________________________________________
opensc-devel mailing list
opensc-devel@lists.opensc-project.org
http://www.opensc-project.org/mailman/listinfo/opensc-devel
