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

Issue #7551 has been updated by drbrain (Eric Hodel).


Regarding your questions:

1) If the best we can do at present is point to a .h file in OpenSSL at present then I don't see a problem with it.

2) For OpenSSL::X509::ExtensionFactory, new documentation would go in ext/openssl/ossl_x509ext.c.  For the most part the class or module implemented is guessable from the file name.  You can look at ext/openssl/ossl_x509name.c for examples (or any of the .c files at the root).

PS: Your patch is great.
----------------------------------------
Bug #7551: Incorrect suggested usage in OpenSSL::X509::ExtensionFactory documentation
https://bugs.ruby-lang.org/issues/7551#change-34725

Author: richard.bradley (Richard Bradley)
Status: Assigned
Priority: Normal
Assignee: MartinBosslet (Martin Bosslet)
Category: DOC
Target version: 2.0.0
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/