Bug #74822 for Net-SSLeay: Documentation for CTX

Thu Feb 09 11:17:06 2012 kmx [...] volny.cz - Ticket created

Subject:	Documentation for CTX_ related functions
Date:	Thu, 09 Feb 2012 17:16:39 +0100
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	kmx <kmx [...] volny.cz>

Hi, I have tried to add documentation to CTX_... related functions + made a bit or reorganization. See attached patch. As for CTX: 1/ some functions are totally unclear to me (I suspect they cannot work correctly - look for ??? in POD) 2/ I have done two little fixes to XS (IMHO obvious errors) 3/ I am NOT gonna add missing tests for CTX_* functions (I wanna focus on X509_* functions - separate RT) Providing that we (I) will probably add even more documentation, it might be worth considering to move documentation into a separate SSLeay.pod The new doc structure looks like this: =head1 NAME =head1 SYNOPSIS =head1 DESCRIPTION =head2 High level functions for accessing web servers =head3 Basic set of functions =head3 Alternate versions of high-level API =head3 Using client certificates =head3 Working through a web proxy =head3 HTTP (without S) API =head2 Certificate verification and Certificate Revocation Lists (CRLs) =head2 Using Net::SSLeay in multi-threaded applications =head3 Initialization =head3 Using callbacks =head3 Using openssl elements =head3 Using other perl modules based on Net::SSLeay =head3 Combining Net::SSLeay with other modules linked with openssl =head3 Threading with get_https and friends =head2 Convenience routines =head2 Initialization =head2 Error handling functions =head2 Sockets =head2 Callbacks =head2 Low level API =head3 Low level API: Version related functions =head3 Low level API: CTX_* related functions =head3 Low level API: RAND_* related functions =head3 Low level API: ASN1_TIME_* related functions =head3 Low level API: X509_* related functions =head3 Low level API: Digest related functions =head3 Low level API: RSA_* related functions =head3 Low level API: Digests related functions =head3 Low level API: BIO_* related functions =head3 Low level API: Other functions =head1 EXAMPLES =head1 LIMITATIONS =head1 KNOWN BUGS AND CAVEATS =head1 DIAGNOSTICS =head1 BUGS AND SUPPORT =head1 AUTHOR =head1 COPYRIGHT =head1 SEE ALSO -- kmx

Message body is not shown because sender requested not to inline it.

Thu Feb 09 16:39:01 2012 mikem [...] open.com.au - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Fri, 10 Feb 2012 07:38:55 +1000
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	Mike McCauley <mikem [...] open.com.au>

HI, thanks for those. Committed in 298. Im OK with SSLeay.pod, but I dont think it is mandatory. Will that work with early perls too? Cheers. On Thursday, February 09, 2012 11:17:08 AM you wrote: Show quoted text

> Thu Feb 09 11:17:06 2012: Request 74822 was acted upon. > Transaction: Ticket created by kmx@volny.cz > Queue: Net-SSLeay > Subject: Documentation for CTX_ related functions > Broken in: (no value) > Severity: (no value) > Owner: Nobody > Requestors: kmx@volny.cz > Status: new > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74822 > > > > Hi, > > I have tried to add documentation to CTX_... related functions + made a > bit or reorganization. See attached patch. > > As for CTX: > 1/ some functions are totally unclear to me (I suspect they cannot work > correctly - look for ??? in POD) > 2/ I have done two little fixes to XS (IMHO obvious errors) > 3/ I am NOT gonna add missing tests for CTX_* functions (I wanna focus > on X509_* functions - separate RT) > > Providing that we (I) will probably add even more documentation, it > might be worth considering to move documentation into a separate SSLeay.pod > > The new doc structure looks like this: > > =head1 NAME > =head1 SYNOPSIS > =head1 DESCRIPTION > =head2 High level functions for accessing web servers > =head3 Basic set of functions > =head3 Alternate versions of high-level API > =head3 Using client certificates > =head3 Working through a web proxy > =head3 HTTP (without S) API > =head2 Certificate verification and Certificate Revocation Lists (CRLs) > =head2 Using Net::SSLeay in multi-threaded applications > =head3 Initialization > =head3 Using callbacks > =head3 Using openssl elements > =head3 Using other perl modules based on Net::SSLeay > =head3 Combining Net::SSLeay with other modules linked with openssl > =head3 Threading with get_https and friends > =head2 Convenience routines > =head2 Initialization > =head2 Error handling functions > =head2 Sockets > =head2 Callbacks > =head2 Low level API > =head3 Low level API: Version related functions > =head3 Low level API: CTX_* related functions > =head3 Low level API: RAND_* related functions > =head3 Low level API: ASN1_TIME_* related functions > =head3 Low level API: X509_* related functions > =head3 Low level API: Digest related functions > =head3 Low level API: RSA_* related functions > =head3 Low level API: Digests related functions > =head3 Low level API: BIO_* related functions > =head3 Low level API: Other functions > =head1 EXAMPLES > =head1 LIMITATIONS > =head1 KNOWN BUGS AND CAVEATS > =head1 DIAGNOSTICS > =head1 BUGS AND SUPPORT > =head1 AUTHOR > =head1 COPYRIGHT > =head1 SEE ALSO > > -- > kmx

-- Mike McCauley mikem@open.com.au Open System Consultants Pty. Ltd 9 Bulbul Place Currumbin Waters QLD 4223 Australia http://www.open.com.au Phone +61 7 5598-7474 Fax +61 7 5598-7070 Radiator: the most portable, flexible and configurable RADIUS server anywhere. SQL, proxy, DBM, files, LDAP, NIS+, password, NT, Emerald, Platypus, Freeside, TACACS+, PAM, external, Active Directory, EAP, TLS, TTLS, PEAP, TNC, WiMAX, RSA, Vasco, Yubikey, MOTP, HOTP, TOTP, DIAMETER etc. Full source on Unix, Windows, MacOSX, Solaris, VMS, NetWare etc.

Thu Feb 09 16:39:03 2012 The RT System itself - Status changed from 'new' to 'open'

Thu Feb 09 17:23:20 2012 kmx [...] volny.cz - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Thu, 09 Feb 2012 23:23:09 +0100
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	kmx <kmx [...] volny.cz>

Show quoted text

> Im OK with SSLeay.pod, but I dont think it is mandatory. Will that work with > early perls too? >

Good question. The oldest I have is 5.8.9 which seems to be OK. Anyway in case the SSLeay.pod will get ignored on some very old perl it only means that documentation will not be installed; the module itself will work. SSleay.pm in Net-SSLeay-1.42 has 85KB, now the trunk version has 152KB, after covering all existing functions I expect 320KB and after adding doc for the new functions I plan to add we will be close to 400KB Pure perl (no pod) version of SSleay.pm has approx 48KB -- kmx

Thu Feb 09 17:36:05 2012 mikem [...] open.com.au - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Fri, 10 Feb 2012 08:35:57 +1000
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	Mike McCauley <mikem [...] open.com.au>

Hi, On Thursday, February 09, 2012 05:23:25 PM you wrote: Show quoted text

> Queue: Net-SSLeay > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74822 > >

> > Im OK with SSLeay.pod, but I dont think it is mandatory. Will that work > > with early perls too?

> > Good question. The oldest I have is 5.8.9 which seems to be OK. > > Anyway in case the SSLeay.pod will get ignored on some very old perl it > only means that documentation will not be installed; the module itself > will work. > > SSleay.pm in Net-SSLeay-1.42 has 85KB, now the trunk version has 152KB, > after covering all existing functions I expect 320KB and after adding > doc for the new functions I plan to add we will be close to 400KB > > Pure perl (no pod) version of SSleay.pm has approx 48KB

OK. Your choice. Cheers. Show quoted text

> > -- > kmx

-- Mike McCauley mikem@open.com.au Open System Consultants Pty. Ltd 9 Bulbul Place Currumbin Waters QLD 4223 Australia http://www.open.com.au Phone +61 7 5598-7474 Fax +61 7 5598-7070 Radiator: the most portable, flexible and configurable RADIUS server anywhere. SQL, proxy, DBM, files, LDAP, NIS+, password, NT, Emerald, Platypus, Freeside, TACACS+, PAM, external, Active Directory, EAP, TLS, TTLS, PEAP, TNC, WiMAX, RSA, Vasco, Yubikey, MOTP, HOTP, TOTP, DIAMETER etc. Full source on Unix, Windows, MacOSX, Solaris, VMS, NetWare etc.

Thu Feb 09 17:52:50 2012 kmx [...] volny.cz - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Thu, 09 Feb 2012 23:52:11 +0100
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	kmx <kmx [...] volny.cz>

Show quoted text

> OK. > Your choice. >

Here the pm-pod splitting commit: pod-split_r298.diff Do not forget to svn add lib/Net/SSLeay.pod Thanks -- kmx

Message body is not shown because sender requested not to inline it.

Thu Feb 09 18:13:46 2012 mikem [...] open.com.au - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Fri, 10 Feb 2012 09:13:42 +1000
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	Mike McCauley <mikem [...] open.com.au>

Hi, OK, .pod works as early as 5.6. Patch did not apply cleanly here :-( But fixed by hand. Committed at 299 Thanks. Cheers. On Thursday, February 09, 2012 05:52:51 PM you wrote: Show quoted text

> Queue: Net-SSLeay > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74822 > >

> > OK. > > Your choice.

> > Here the pm-pod splitting commit: pod-split_r298.diff > > Do not forget to svn add lib/Net/SSLeay.pod > > Thanks > > -- > kmx

-- Mike McCauley mikem@open.com.au Open System Consultants Pty. Ltd 9 Bulbul Place Currumbin Waters QLD 4223 Australia http://www.open.com.au Phone +61 7 5598-7474 Fax +61 7 5598-7070 Radiator: the most portable, flexible and configurable RADIUS server anywhere. SQL, proxy, DBM, files, LDAP, NIS+, password, NT, Emerald, Platypus, Freeside, TACACS+, PAM, external, Active Directory, EAP, TLS, TTLS, PEAP, TNC, WiMAX, RSA, Vasco, Yubikey, MOTP, HOTP, TOTP, DIAMETER etc. Full source on Unix, Windows, MacOSX, Solaris, VMS, NetWare etc.

Mon Feb 13 16:42:30 2012 kmx [...] volny.cz - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Mon, 13 Feb 2012 22:42:14 +0100
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	kmx <kmx [...] volny.cz>

Not so huge progress this time, but here comes another set of pod documentation - pod-hacking-round2_r299.diff (changing only SSLeay.pod so no worry about any broken functionality). FYI: There are another approx 2000 line of pod doc (=2.5x more than this patch) that need to polish and commit - after that we can turn on 02_pod_coverage.t -- kmx

Message body is not shown because sender requested not to inline it.

Mon Feb 13 17:34:02 2012 mikem [...] open.com.au - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Tue, 14 Feb 2012 08:33:56 +1000
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	Mike McCauley <mikem [...] open.com.au>

Hi, Very thorough! Committed in 300 Cheers. On Monday, February 13, 2012 04:42:33 PM you wrote: Show quoted text

> Queue: Net-SSLeay > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74822 > > > Not so huge progress this time, but here comes another set of pod > documentation - pod-hacking-round2_r299.diff (changing only SSLeay.pod > so no worry about any broken functionality). > > FYI: There are another approx 2000 line of pod doc (=2.5x more than this > patch) that need to polish and commit - after that we can turn on > 02_pod_coverage.t > > -- > kmx

-- Mike McCauley mikem@open.com.au Open System Consultants Pty. Ltd 9 Bulbul Place Currumbin Waters QLD 4223 Australia http://www.open.com.au Phone +61 7 5598-7474 Fax +61 7 5598-7070 Radiator: the most portable, flexible and configurable RADIUS server anywhere. SQL, proxy, DBM, files, LDAP, NIS+, password, NT, Emerald, Platypus, Freeside, TACACS+, PAM, external, Active Directory, EAP, TLS, TTLS, PEAP, TNC, WiMAX, RSA, Vasco, Yubikey, MOTP, HOTP, TOTP, DIAMETER etc. Full source on Unix, Windows, MacOSX, Solaris, VMS, NetWare etc.

Tue Feb 14 20:08:30 2012 kmx [...] volny.cz - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Wed, 15 Feb 2012 02:08:06 +0100
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	kmx <kmx [...] volny.cz>

Another pod patch + some simple fixes to SSLeay.xs. Last 15 functions left. -- kmx

Message body is not shown because sender requested not to inline it.

Tue Feb 14 20:22:17 2012 mikem [...] open.com.au - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Wed, 15 Feb 2012 11:22:16 +1000
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	Mike McCauley <mikem [...] open.com.au>

Hi, On Tuesday, February 14, 2012 08:08:32 PM you wrote: Show quoted text

> Queue: Net-SSLeay > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74822 > > > Another pod patch + some simple fixes to SSLeay.xs.

Thanks. Committed with 301 Cheers. Show quoted text

> > Last 15 functions left. > > -- > kmx

-- Mike McCauley mikem@open.com.au Open System Consultants Pty. Ltd 9 Bulbul Place Currumbin Waters QLD 4223 Australia http://www.open.com.au Phone +61 7 5598-7474 Fax +61 7 5598-7070 Radiator: the most portable, flexible and configurable RADIUS server anywhere. SQL, proxy, DBM, files, LDAP, NIS+, password, NT, Emerald, Platypus, Freeside, TACACS+, PAM, external, Active Directory, EAP, TLS, TTLS, PEAP, TNC, WiMAX, RSA, Vasco, Yubikey, MOTP, HOTP, TOTP, DIAMETER etc. Full source on Unix, Windows, MacOSX, Solaris, VMS, NetWare etc.

Wed Feb 15 08:47:31 2012 kmx [...] volny.cz - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Wed, 15 Feb 2012 14:47:13 +0100
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	kmx <kmx [...] volny.cz>

Last pod documentation commit - pod-hacking-round4_r301.diff Small fixes to XS code + one new trivial function SSL_CIPHER_get_name And one more thing - 02_pod_coverage.t is turned ON passing all tests - never ever allow a new function without at least a short doc :) Perhaps this ticket can be closed, other issues I have found out during doc writting I am gonna report as separate RTs. -- kmx

Message body is not shown because sender requested not to inline it.

Wed Feb 15 16:57:36 2012 mikem [...] open.com.au - Correspondence added

Subject:	Re: [rt.cpan.org #74822] Documentation for CTX_ related functions
Date:	Thu, 16 Feb 2012 07:57:28 +1000
To:	bug-Net-SSLeay [...] rt.cpan.org
From:	Mike McCauley <mikem [...] open.com.au>

Hi, thanks again for another comprehensive patch. However, with this patch, I see a compiler warning with openssl 1.0.0 on Linux SSLeay.c: In function ‘XS_Net__SSLeay_CIPHER_get_name’: SSLeay.c:6190:9: warning: assignment discards ‘const’ qualifier from pointer target type [enabled by default] and a test error: t/local/02_pod_coverage.t .............. 1/2 # Failed test 'Pod coverage on Net::SSLeay' # at t/local/02_pod_coverage.t line 11. # Coverage for Net::SSLeay is 99.7%, with 1 naked subroutine: # add_dir_cert_subjects_to_stack # Looks like you failed 1 test of 2. I have fixed these issues by: changing the signature of SSLeay_CIPHER_get_name to const char 8 Adding some doc for add_dir_cert_subjects_to_stack committed to 302. Thanks. Cheers. On Wednesday, February 15, 2012 08:47:32 AM you wrote: Show quoted text

> Queue: Net-SSLeay > Ticket <URL: https://rt.cpan.org/Ticket/Display.html?id=74822 > > > Last pod documentation commit - pod-hacking-round4_r301.diff > > Small fixes to XS code + one new trivial function SSL_CIPHER_get_name > > And one more thing - 02_pod_coverage.t is turned ON passing all tests - > never ever allow a new function without at least a short doc :) > > Perhaps this ticket can be closed, other issues I have found out during > doc writting I am gonna report as separate RTs. > > -- > kmx

-- Mike McCauley mikem@open.com.au Open System Consultants Pty. Ltd 9 Bulbul Place Currumbin Waters QLD 4223 Australia http://www.open.com.au Phone +61 7 5598-7474 Fax +61 7 5598-7070 Radiator: the most portable, flexible and configurable RADIUS server anywhere. SQL, proxy, DBM, files, LDAP, NIS+, password, NT, Emerald, Platypus, Freeside, TACACS+, PAM, external, Active Directory, EAP, TLS, TTLS, PEAP, TNC, WiMAX, RSA, Vasco, Yubikey, MOTP, HOTP, TOTP, DIAMETER etc. Full source on Unix, Windows, MacOSX, Solaris, VMS, NetWare etc.

Wed Feb 15 17:07:05 2012 MIKEM [...] cpan.org - TimeWorked changed from (no value) to '15'

Wed Feb 15 17:07:05 2012 MIKEM [...] cpan.org - Status changed from 'open' to 'resolved'

Wed Feb 15 17:07:06 2012 MIKEM [...] cpan.org - Given to MIKEM

Bug #74822 for Net-SSLeay: Documentation for CTX_ related functions