[ruby-core:50830] [ruby-trunk - Bug #7551][Open] Incorrect suggested usage in OpenSSL::X509::ExtensionFactory documentation

Issue #7551 has been reported by richard.bradley (Richard Bradley).

----------------------------------------
Bug #7551: Incorrect suggested usage in OpenSSL::X509::ExtensionFactory documentation
https://bugs.ruby-lang.org/issues/7551

Author: richard.bradley (Richard Bradley)
Status: Open
Priority: Normal
Assignee: 
Category: 
Target version: 
ruby -v: ruby 1.9.3p194 (2012-04-20) [i386-mingw32]


The OpenSSL::X509::ExtensionFactory class doesn't have any documentation of its own:
 - http://www.ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL/X509/ExtensionFactory.html
Its usage is shown in a few examples on the OpenSSL lib homepage:
 - http://www.ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL.html
.. however several of these examples are wrong.

The examples show calling "extension_factory.create_extension" and not saving the return value.
If you do not pass the returned value to "cert.add_extension", then the requested extension value will not be added to the certificate.
The attached patch fixes this problem.

The examples on the Certificate documentation are already correct:
 - http://ruby-doc.org/stdlib-1.9.3/libdoc/openssl/rdoc/OpenSSL/X509/Certificate.html


Aside about further documentation:
----------------------------------

I would be happy to add a bit of documentation to the Ruby OpenSSL lib, but:
 1. I would like to add cites to the underlying OpenSSL lib, but that appears to me to be sparsely documented, if at all (for example, the "see objects.h" cite I added in the attached patch is literally the best documentation I could find for the underlying implementation)
 2. It's not clear to me which .c comments in which files will get compiled into the rubydoc
.. so perhaps someone else would be better placed to add this documentation. (Although given how long the Ruby OpenSSL lib has existed in its current woefully underdocumented state, perhaps no-one else will?)

If anyone has any suggestions for how I can fix 1 / 2 above, I would be happy to submit further documentation patches.
For now, this is all I have :-)


(If the attached patch is in the wrong format, sorry. Please let me know if so, and what format you prefer, and I can resubmit.)


-- 
http://bugs.ruby-lang.org/