Skip to content

Add ext/openssl/.document so new C files are included in Ruby's docs - #1159

Open
ksss wants to merge 1 commit into
ruby:masterfrom
ksss:add-document-file
Open

ksss wants to merge 1 commit into
ruby:masterfrom
ksss:add-document-file

Conversation

@ksss

@ksss ksss commented Nov 19, 2026

Copy link
Copy Markdown

Ruby's documentation is built from ruby/ruby's ext/.document, which currently lists each openssl/ossl_*.c file explicitly. That file lives only in ruby/ruby, so source files added here are not picked up unless someone also updates ruby/ruby by hand.

This has already happened twice:

  • ossl_provider.c is missing from ext/.document on both ruby_4_0 and master, so OpenSSL::Provider and OpenSSL::Provider::ProviderError have no documentation in Ruby 4.0 (ri OpenSSL::Provider → "Nothing known about OpenSSL::Provider"), even though the C source has doc comments.
  • ossl_hpke.c is missing on master as well.

This PR adds ext/openssl/.document with:

lib
*.c

It is synced to ruby/ruby along with the rest of ext/openssl. After that, the openssl/... entries in ruby/ruby's ext/.document can be replaced with a single openssl/ line, and RDoc will follow this file. ruby/io-console uses the same layout (ext/io/console/.document, ruby/ruby@c7731b35eb).

Notes:

  • lib refers to ext/openssl/lib in the ruby/ruby tree. It does not exist in this repository, and RDoc ignores it here. io-console's .document also lists lib/size.rb, which only exists in the ruby/ruby tree.
  • *.c matches the current explicit list exactly (.h, extconf.rb and depend stay excluded), and covers future files automatically.
  • This repository's own rake rdoc passes file globs directly (ext/**/*.c), so it is not affected.

I checked this on a ruby_4_0 tree with RDoc 8.1.0. With this file in place and ext/.document changed to openssl/, the generated ri data is identical to adding openssl/ossl_provider.c to the current list, and includes OpenSSL::Provider.

Follow-up in ruby/ruby (after sync)

-openssl/lib
-openssl/ossl.c
-openssl/ossl_asn1.c
-...
-openssl/ossl_x509store.c
+openssl/

🤖 Generated with Claude Code

ruby/ruby's ext/.document lists every openssl/ossl_*.c file one by one.
That list is not part of this repository, so new source files are
silently left out of Ruby's documentation. ossl_provider.c (added in
2023) and ossl_hpke.c are missing, and as a result OpenSSL::Provider
has no entry in Ruby's ri/HTML docs.

Ship a .document in ext/openssl so the file list travels with the
sync, as ruby/io-console does in ext/io/console/.document.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@rhenium

rhenium commented Nov 19, 2026

Copy link
Copy Markdown
Member

Thanks for the catch! I hadn't realized ext/.document in ruby/ruby needed to be sync'ed.

However, I feel this would be better fixed in ruby/ruby, since the file is not used in this repository. (Could ruby/ruby's ext/.document perhaps use ext/openssl/*.c, assuming that's supported?)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants