YARD Compatible method documentation across lib #21142
Description
After looking at different method documentation across different files within MSF, I noticed they are rather inconsistent. This is likely due to the age of metasploit's code (and subsequently the improvements in documentation strategies), MANY different authors, and inconsistent requirements for PRs. I had Claude AI take a look at lib/msf and lib/rex to figure out what the worst offenders were to create a priority for updating them. I don't think someone should try to tackle all of these, I think a better strategy would be to do a PR per file, this will make it quick and easy to review.
Below is what Claude generated:
Documentation coverage gaps in lib/msf and lib/rex
Summary
A static analysis of all Ruby files in lib/msf and lib/rex (minimum 5 methods per file) found significant documentation gaps across both directories.
| Metric | Count | % of total |
|---|---|---|
| Files analyzed | 812 | — |
| Total methods | 10,440 | — |
| Methods with no comment at all | 4,272 | 40.9% |
| Methods with a comment but no YARD tags | 3,595 | 34.4% |
| Methods with YARD documentation | 2,573 | 24.6% |
Only 1 in 4 methods across lib/msf and lib/rex has any YARD documentation. Over 40% have no comment of any kind.
Most undocumented files
Files ranked by absolute count of methods with no comment (plain prose or YARD). Minimum 5 methods. Top 40.
| File | Undocumented | Total methods | % undocumented |
|---|---|---|---|
msf/ui/console/command_dispatcher/db.rb |
47 | 74 | 63.5% |
msf/core/exploit/remote/vim_soap.rb |
45 | 45 | 100% |
rex/proto/ntlm/base.rb |
40 | 40 | 100% |
msf/core/exploit/remote/rdp.rb |
39 | 73 | 53.4% |
msf/core/payload/adapter/fetch.rb |
38 | 40 | 95.0% |
rex/post/meterpreter/ui/console/command_dispatcher/core.rb |
38 | 64 | 59.4% |
msf/ui/console/command_dispatcher/modules.rb |
38 | 74 | 51.4% |
msf/ui/console/command_dispatcher/core.rb |
38 | 87 | 43.7% |
rex/post/io.rb |
36 | 38 | 94.7% |
rex/post/file.rb |
36 | 41 | 87.8% |
rex/proto/ms_dtyp.rb |
34 | 35 | 97.1% |
rex/post/file_stat.rb |
34 | 39 | 87.2% |
rex/parser/acunetix_document.rb |
31 | 36 | 86.1% |
rex/proto/drda/packet.rb |
30 | 31 | 96.8% |
rex/parser/nmap_document.rb |
27 | 31 | 87.1% |
msf/core/auxiliary/web/http.rb |
26 | 26 | 100% |
rex/parser/nexpose_raw_document.rb |
26 | 31 | 83.9% |
msf/core/exploit/remote/smb/client/psexec_ms17_010.rb |
26 | 31 | 83.9% |
msf/base/sessions/command_shell.rb |
26 | 48 | 54.2% |
rex/ui/text/bidirectional_pipe.rb |
25 | 26 | 96.2% |
rex/proto/http/web_socket/amazon_ssm.rb |
25 | 26 | 96.2% |
msf/core/payload/windows/encrypted_reverse_tcp.rb |
24 | 26 | 92.3% |
rex/parser/nexpose_simple_document.rb |
22 | 24 | 91.7% |
msf/core/auxiliary/prometheus.rb |
22 | 24 | 91.7% |
rex/post/meterpreter/extensions/kiwi/kiwi.rb |
22 | 30 | 73.3% |
rex/post/smb/ui/console/command_dispatcher/shares.rb |
22 | 32 | 68.8% |
rex/parser/appscan_document.rb |
21 | 24 | 87.5% |
msf/core/evasion.rb |
21 | 26 | 80.8% |
msf/ui/console/command_dispatcher/dns.rb |
21 | 29 | 72.4% |
msf/core/auxiliary/auth_brute.rb |
21 | 43 | 48.8% |
rex/parser/outpost24_document.rb |
20 | 20 | 100% |
msf/core/modules/external/bridge.rb |
20 | 21 | 95.2% |
rex/post/hwbridge/ui/console/command_dispatcher/core.rb |
20 | 37 | 54.1% |
rex/post/meterpreter/extensions/android/android.rb |
19 | 19 | 100% |
msf/core/exception.rb |
19 | 19 | 100% |
msf/core/exploit/dect_coa.rb |
19 | 19 | 100% |
msf/ui/debug.rb |
19 | 21 | 90.5% |
rex/proto/ntlm/message.rb |
19 | 23 | 82.6% |
msf/core/payload/generic.rb |
19 | 27 | 70.4% |
msf/core/exploit/capture.rb |
19 | 36 | 52.8% |
Most non-YARD files
Files ranked by absolute count of methods lacking YARD tags (@param, @return, @raise, @yield, @option, etc.). This includes methods with plain-prose comments that were never migrated to YARD. Top 40.
| File | Non-YARD methods | Total methods | % non-YARD |
|---|---|---|---|
msf/core/exploit.rb |
79 | 83 | 95.2% |
msf/core/exploit/remote/rdp.rb |
69 | 73 | 94.5% |
msf/ui/console/command_dispatcher/db.rb |
68 | 74 | 91.9% |
msf/ui/console/command_dispatcher/core.rb |
65 | 87 | 74.7% |
msf/ui/console/command_dispatcher/modules.rb |
64 | 74 | 86.5% |
rex/post/meterpreter/ui/console/command_dispatcher/core.rb |
63 | 64 | 98.4% |
rex/proto/smb/client.rb |
59 | 59 | 100% |
rex/post/meterpreter/packet.rb |
52 | 52 | 100% |
msf/base/sessions/command_shell.rb |
46 | 48 | 95.8% |
msf/core/exploit/remote/vim_soap.rb |
45 | 45 | 100% |
rex/post/meterpreter/ui/console/command_dispatcher/stdapi/sys.rb |
42 | 44 | 95.5% |
rex/post/file.rb |
41 | 41 | 100% |
rex/proto/ntlm/base.rb |
40 | 40 | 100% |
msf/core/payload/adapter/fetch.rb |
40 | 40 | 100% |
rex/post/file_stat.rb |
39 | 39 | 100% |
rex/ui/text/dispatcher_shell.rb |
39 | 42 | 92.9% |
rex/post/io.rb |
38 | 38 | 100% |
rex/post/hwbridge/ui/console/command_dispatcher/core.rb |
37 | 37 | 100% |
msf/core/post/windows/registry.rb |
37 | 41 | 90.2% |
rex/parser/acunetix_document.rb |
36 | 36 | 100% |
msf/core/encoder.rb |
36 | 36 | 100% |
msf/core/exploit/capture.rb |
36 | 36 | 100% |
msf/base/sessions/meterpreter.rb |
36 | 37 | 97.3% |
rex/proto/ms_dtyp.rb |
34 | 35 | 97.1% |
rex/post/meterpreter/ui/console/command_dispatcher/stdapi/fs.rb |
32 | 32 | 100% |
rex/post/meterpreter/ui/console/command_dispatcher/kiwi.rb |
32 | 34 | 94.1% |
msf/core/payload.rb |
32 | 36 | 88.9% |
msf/core/framework.rb |
32 | 37 | 86.5% |
msf/core/auxiliary/auth_brute.rb |
32 | 43 | 74.4% |
rex/parser/nmap_document.rb |
31 | 31 | 100% |
rex/parser/nexpose_raw_document.rb |
31 | 31 | 100% |
rex/proto/drda/packet.rb |
31 | 31 | 100% |
msf/core/exploit/remote/smb/client/psexec_ms17_010.rb |
31 | 31 | 100% |
msf/core/session.rb |
30 | 30 | 100% |
msf/ui/console/command_dispatcher/developer.rb |
29 | 30 | 96.7% |
rex/post/meterpreter/client_core.rb |
29 | 32 | 90.6% |
rex/post/smb/ui/console/command_dispatcher/shares.rb |
29 | 32 | 90.6% |
rex/ui/text/shell.rb |
28 | 28 | 100% |
msf/core/payload_set.rb |
28 | 29 | 96.6% |
msf/ui/console/command_dispatcher/dns.rb |
28 | 29 | 96.6% |
Notes
- Analysis was run against
lib/msfandlib/rexonly. Vendored libraries (lib/net,lib/snmp,lib/rbmysql, etc.) were excluded. - A method counts as "commented" if there is at least one non-empty
#comment line in the block immediately preceding thedef. - A method counts as "YARD documented" if that comment block contains at least one recognized YARD tag.
- Files with fewer than 5 methods were excluded.
- Several core files stand out as notable gaps:
msf/core/exploit.rb(the base class for all exploits) has 79/83 non-YARD methods;msf/core/framework.rb,msf/core/payload.rb,msf/core/encoder.rb, andmsf/core/session.rbare all 85–100% non-YARD.