Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Writing documentation can be fun with plugin sy...
Search
Masafumi Okura
February 01, 2025
Programming
0
190
Writing documentation can be fun with plugin system
https://fortee.jp/burikaigi-2025/proposal/03ac7594-fce1-4dad-9dd0-c37649127f90
Masafumi Okura
February 01, 2025
Tweet
Share
More Decks by Masafumi Okura
See All by Masafumi Okura
My KaigiEffect at RubyKaigi 2025, part 1
okuramasafumi
1
43
Alba: Why, How and What's So Interesting
okuramasafumi
0
380
Why did my proposals get rejected?
okuramasafumi
1
680
A suggestion for the future of RDoc
okuramasafumi
1
330
15 JSON serializers for Ruby
okuramasafumi
2
390
Tech Events, Should We See Them from the Outside or the Inside?
okuramasafumi
1
69
Creating gems 101
okuramasafumi
2
140
How NOT to make your DSL terrible
okuramasafumi
0
590
オブジェクトしこう
okuramasafumi
2
480
Other Decks in Programming
See All in Programming
The Niche of CDK Grant オブジェクトって何者?/the-niche-of-cdk-what-isgrant-object
hassaku63
1
660
AIのメモリー
watany
7
450
はじめてのWeb API体験 ー 飲食店検索アプリを作ろうー
akinko_0915
0
160
CDK引数設計道場100本ノック
badmintoncryer
2
520
バイブスあるコーディングで ~PHP~ 便利ツールをつくるプラクティス
uzulla
1
190
構文解析器入門
ydah
7
1.7k
AI時代のソフトウェア開発を考える(2025/07版) / Agentic Software Engineering Findy 2025-07 Edition
twada
PRO
102
38k
知って得する@cloudflare_vite-pluginのあれこれ
chimame
1
110
Yes, You Can Work on Rails & any other Gem
kaspth
0
110
Flutterで備える!Accessibility Nutrition Labels完全ガイド
yuukiw00w
0
180
バイブコーディング超えてバイブデプロイ〜CloudflareMCPで実現する、未来のアプリケーションデリバリー〜
azukiazusa1
2
660
商品比較サービス「マイベスト」における パーソナライズレコメンドの第一歩
ucchiii43
0
190
Featured
See All Featured
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
Code Reviewing Like a Champion
maltzj
524
40k
Product Roadmaps are Hard
iamctodd
PRO
54
11k
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
15
1.6k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Practical Orchestrator
shlominoach
189
11k
Designing for humans not robots
tammielis
253
25k
Rebuilding a faster, lazier Slack
samanthasiow
83
9.1k
The World Runs on Bad Software
bkeepers
PRO
70
11k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
2.9k
Making the Leap to Tech Lead
cromwellryan
134
9.4k
It's Worth the Effort
3n
185
28k
Transcript
ָ͍͠υΩϡϝϯςʔγϣϯ Λࢦͯ͠ —RDoc֦ுػೳج൫ BuriKaigi 2025 OKURA Masafumi, 2025-02-01
͡Ίʹɿ͜ͷൃදʹ͓͚Δ༻ޠͷఆٛ • υΩϡϝϯτɿιʔείʔυʹίϝϯτͱͯ͠ਵ͢ΔλΠϓͷจ ॻɺREADMEͳͲݪଇతʹআ֎ • υΩϡϝϯςʔγϣϯɿυΩϡϝϯτͷू߹ʢݩʑͷҙຯʣɺ͋Δ͍ υΩϡϝϯτΛهड़͢Δ͜ͱʢಠࣗͷҙຯʣ • υΩϡϝϯςʔγϣϯπʔϧɿهड़͞ΕͨυΩϡϝϯτΛਓؒʹΑͬ ͯར༻Մೳͳܗʹม͢Δπʔϧ
• RDocɿRubyʹඪ४ఴ͞Ε͍ͯΔυΩϡϝϯςʔγϣϯπʔϧ
υΩϡϝϯτΛ ॻ͘ͷָ͍͠ Ͱ͔͢ʁ
ࢲ͋·Γ ָ͋͘͠Γ·ͤΜ :)
WHY?
ͳͥυΩϡϝϯτΛॻ͘ͷָ͘͠ͳ͍ͷ͔ • ίʔυΛॻ͘΄͏ָ͕͍͔͠Β • Θ͔Δ • ͨ͘͞Μॻ͔ͳ͍͚ͯ͘ͳ͍͔Β • ͳΜͱ͔Ͱ͖ΔͷͰʁ •
ॻ͍ͨυΩϡϝϯτ͕ʹཱͭؾ͕͠ͳ͍͔Β • ʹཱͭΑ͏ͳυΩϡϝϯτΛੜͰ͖ͨΒʁ
ͨͷ͍͠υΩϡϝϯ ςʔγϣϯͷͨΊʹɺ υΩϡϝϯςʔγϣϯ πʔϧ͕Ͱ͖Δ͜ͱ
1. লྗԽ
2. ༗༻Խ
͋ͳͨ୭ʁ
ࣗݾհ • ໊લɿେխ࢙ʢ͓͓͘Β·͞;Έʣ • ॴଐɿϑϦʔϥϯε • ՝֎׆ಈɿKaigi on RailsɺTokyoWomen.rbɺRubygemsίʔυϦʔ σΟϯά෦ʢҎ্ओ࠵ʣɺOSS׆ಈʢGitHub
Star ߹ܭ1000ʣ • ࢲͱBuriKaigiɿ2020ొஃʢinstance_evalʣɺ2022ొஃ ʢDSLʣɺ2024ొஃʢRubyʹBoolean͕ͳ͍ཧ༝ʣ
None
None
None
ָ͍͠υΩϡϝϯςʔγϣϯ Λࢦͯ͠—RDoc֦ுػೳج ൫ BuriKaigi 2025 OKURA Masafumi, 2025-02-01
Rubyist
Ruby
RDoc
RDocͱ • Rubyʹඪ४ఴ͞Ε͍ͯΔʢผ్ͷΠϯετʔϧ͕ෆཁͳʣυΩϡϝϯςʔ γϣϯπʔϧ • HTMLυΩϡϝϯτΛੜ͢Δ`rdoc`ίϚϯυͱίϚϯυϥΠϯ͔ΒυΩϡϝ ϯτΛӾཡ͢Δ`ri`πʔϧΛಉࠝ • RDoc͕σϑΥϧτͰѻ͏ϑΥʔϚοτ`RDϑΥʔϚοτ`ͱݴ͏͕ɺRDoc ϑΥʔϚοτͱݺΕΔ͜ͱ͋Δ
• Ruby on RailsͰ࠾༻͞Ε͍ͯΔଞɺRubyຊମ͜ͷه๏
None
͍͜͠
YARD
YARDͱ • Rubyͷඇඪ४υΩϡϝϯςʔγϣϯπʔϧ • ϥΠϒϥϦʹ͓͚ΔγΣΞѹతʹߴ͍ • ಠࣗͷʢ@returnͷΑ͏ͳʣه๏Λ࣋ͭ • ͪͳΈʹ໊শ”Yay! A
Ruby Documentation”ͷ಄ࣈޠ
None
υΩϡϝϯςʔγϣϯ πʔϧ ʢͱϑΥʔϚοτʣ ͕2ͭ͋Δʂ
RubyͷੈքͰ υΩϡϝϯςʔγϣϯ πʔϧ͕Δ͖͜ͱ
0. πʔϧͷ ౷߹
͓ॻ͖ • πʔϧͷ౷߹ • υΩϡϝϯςʔγϣϯͷলྗԽ • υΩϡϝϯςʔγϣϯͷ༗༻Խ
௨Իͱͯ͠ͷ ֦ுػೳج൫
0. πʔϧͷ ౷߹
RDoc or YARD
RDoc or YARD
ͳͥRDocͳͷ͔ • ඪ४ఴ͞Ε͍ͯΔͷͰผ్ͷΠϯετʔϧͳͲ͕ෆཁ • RDocͳ͘ͳΔ͜ͱͳ͍ • CRubyͷιʔείʔυͷυΩϡϝϯτΛղऍͰ͖ΔͷRDocͷΈ • YARDͷϝϯςφϯεঢ়گ͕ෆ҆ •
େ͖Ίͷվળ࠷ۙগͳ͍͠ɺϝϯςφϯεجຊݸਓ͕͍ͯ͠ Δ
Ͳ͏౷߹͢Δʁ
֦ுػೳج൫Ͱ Γ͍ͨʂ
ͳ֦ͥுػೳج൫ͳͷ͔ • YARDؔͷػೳৗʹ͏ͱݶΒͳ͍ • ֦ுػೳʹͯ͠औΓ֎͠Մೳʹ͢Δ • ຊମʹ͍ۙͱ͜ΖʹೖΕΔͱϝϯςφϯεΛࠔʹ͢ΔՄೳੑ͕͋Δ • YARDຊମͷίʔυΛ͍ͨ͘ͳ͍ͷͰίʔυ1͔Βॻ͘ •
ํΛܾΊΔࣗ༝͕͋Δ
֦ுػೳج൫ͷઃܭ • RDocͷطଘίʔυ͔ΒΠϕϯτΛൃՐͤ͞Δʢྫɿpost_parseʣ • ֤֦ுػೳΠϕϯτΛϦοεϯ͠ɺڥΦϒδΣΫτΛड͚औΓɺ มߋ͢Δ • ڥΦϒδΣΫτRDocຊମͷใ֤֦ுػೳ͔Βड͚औͬͨ σʔλΛอ࣋͢Δ •
RDocͷطଘίʔυͰҙͷλΠϛϯάͰݱࡏͷڥΛࢀর͢Δ
֦ுػೳج൫ͰYARDΛRDocʹ౷߹͢Δ • ·ͣYARDύʔαʔΛ࡞Δ • खॻ͖ͱύʔαʔδΣωϨʔλʔͷ2ͭͷखஈ͕͋Δ͕ɺ͓ͦΒ͘खॻ͖ͷํָ͕ • ίϝϯτจࣈྻͷऔಘ͕ऴΘͬͨλΠϛϯάͰΠϕϯτΛൃՐ͢Δ • YARD֦ுػೳ͕ΠϕϯτΛϦοεϯ͠ɺڥΦϒδΣΫτ͔ΒίϝϯτจࣈྻΛऔ ಘ͢Δ
• YARDύʔαʔͰίϝϯτจࣈྻΛύʔε͠ɺܕใͳͲΛऔಘͯ͠ڥΦϒδΣΫ τʹอଘ͢Δ
1. লྗԽ
υΩϡϝϯτΛ ॻ͘ͷ ΊΜͲ͍͘͞…
υΩϡϝϯτͷΊΜͲ͍͘͞ɺ͋Δ͋Δ • `@example`తͳίʔυྫ͕͘ͳͬͯεΫϩʔϧ͠ͳ͍ͱ࣍ͷϝιο υʹͨͲΓண͚ͳ͍ • ϝιουͷ༷͕ॻ͍ͯ͋Δ͚Ͳɺࡉ͔͍ͱ͜ΖΛΔͨΊʹ݁ہ࣮ ͱςετίʔυΛಡΉ • ʲRubyݶఆʳҾฦΓͷܕΛυΩϡϝϯςʔγϣϯπʔϧݻ༗ ͷϑΥʔϚοτͰॻ͚͘ͲɺͦΕͱผʹܕπʔϧͷܕ͋Δ
1ɿ example͕͍
ղܾࡦ1ɿ example ผϑΝΠϧʹ͢Δ
exampleผͷϑΝΠϧʹ͢Δ • ϥΠϒϥϦͩͱ`examples`σΟϨΫτϦ͕͋Δ͜ͱଟ͍ͷͰɺͦ͜ ʹʮͲͷΫϥεϝιουʹඥ͔͘ʯͷλά͕͚͍͚Δ͔ • ϓϩμΫτͩͱɺςετίʔυ͕࣮ࡍͷར༻ྫʹ͍ۙ߹͕ଟ͍ͷ ͰɺςετίʔυΛexampleͱͯ͠ར༻Ͱ͖ͳ͍͔ • ֦ுػೳͱͯ͠ʮσʔλιʔεʯͷ֓೦Λಋೖͯ͠ɺίϝϯτจࣈྻ Ҏ֎͔ΒಘͨใΛ౷߹͍ͨ͠
2ɿ ݁ہίʔυ ςετίʔυΛಡΉ
ղܾࡦ2ɿ ςετίʔυ͔Β υΩϡϝϯτΛ ੜ͢Δ
ςετίʔυ͔ΒυΩϡϝϯτΛੜ͢Δ • RubyͰRSpecͱ͍͏ςεςΟϯάϥΠϒϥϦ͕͘ΘΕ͍ͯΔ • RSpecʹ`—format documentation`ͱ͍͏Φϓγϣϯ͕͋Δ • exampleͷ߹ͱಉ༷ʹ֦ுػೳ͕RSpecΛσʔλιʔεͱͯ͠ར༻ ͠ɺӾཡ࣌ʹखॻ͖ͷυΩϡϝϯτͱϚʔδ͢Δ •
Ҋ1ɿRSpecͷग़ྗΛར༻͢Δʢ࣮ߦඞཁʣ • Ҋ2ɿRSpecͷιʔείʔυΛύʔε͢Δʢ࣮ߦෆཁʣ
3ɿ ܕ͕υΩϡϝϯτ ͱઐ༻πʔϧͰผ
ղܾࡦ3ɿ ެࣜͷܕʢRBSʣ ʹἧ͑Δ
ͷɺલʹ
Rubyͷܕࣄʹ͍͓ͭͯ͞Β͍ • ެࣜͷܕγεςϜͰ͋ΔRBSͱɺඇެࣜͷܕγεςϜͰ͋ΔSorbet ʢRBIʣ͕ଘࡏ͢Δ • RBSͱRBIݱঢ়ඇޓͰผʑͷΤίγεςϜ͕ଘࡏ͢Δ • RBSผϑΝΠϧʹهड़͢Δํ͕ࣜओྲྀʢޙड़ʣɺRBIιʔείʔυ ʹݴޠDSLͱͯ͠هड़͢Δ •
YARDʹಠࣗͷܕه๏ʢܕݕࠪͳͲͳ͠ʣ͕ଘࡏ͢Δ
RubyͷܕγεςϜͱυΩϡϝϯτͷ݉Ͷ߹͍ • SorbetʢRBIʣίϝϯτͱಉ͡ҐஔʹRubyίʔυͱͯ͠ॻ͘ • ඪ४ͰυΩϡϝϯτʹܕใΛදࣔͰ͖ͳ͍ • RBSʹ࠷ۙrbs-inlineͱ͍͏ํ͕ࣜੜ·ΕɺRubyϑΝΠϧʹܕ ใΛهड़Ͱ͖ΔΑ͏ʹͳͬͨ • υΩϡϝϯτʹө͞Εͳ͍
• ࡞ऀతʹYARDʹد͍͖͍ͤͯͨΒ͍͠
None
Έ߹Θͤരൃʹ֦ுػೳج൫ͰରԠ͢Δ • ݸผͷϓϥάΠϯʢྫ͑RBI -> YARDʣଘࡏ͢Δ͕ɺͦΕΒ͕ݸ ผʹϝϯςφϯε͞ΕΔͷେมͰޮ͕ѱ͍ • ܕγεςϜͱੜ͞ΕΔHTMLυΩϡϝϯτͷதؒʹRDocཱ͕ͭ͜ͱ ͰΈ߹ΘͤͷΛݮΒ͢ʢLSPతͳൃʣ •
ܕγεςϜ֦ுػೳ͕ܕใΛυΩϡϝϯτ͚ʹมͯ͠ɺHTML ੜ෦RDocʹͤΔ
2. ༗༻Խ
͔ͤͬ͘ υΩϡϝϯτΛ ࡞ͬͯ ݟͯΒ͑ͳ͍…
υΩϡϝϯτΛ Ͳ͏ͬͯ΄͍͠ ͔
ΞϓϦέʔγϣϯ or ϥΠϒϥϦ
ΞϓϦέʔγϣϯʹ͓͚ΔυΩϡϝϯτ׆༻ • LSPʢLanguage Server ProtocolʣͰυΩϡϝϯτΛදࣔ͢Δ • https://microsoft.github.io/language-server-protocol/ speci fi cations/lsp/3.17/speci
fi cation/ #textDocument_signatureHelp • Railsίϯιʔϧ͔ΒυΩϡϝϯτͷஅยΛදࣔͯ͠ɺΫϦοΫ͢Δͱ ؔ࿈͢ΔΦϯϥΠϯυΩϡϝϯτʹҠಈ͢Δʁ • υΩϡϝϯτΛMarkdownͰग़ྗͯ͠esaKibelaͳͲͱ࿈ܞ͢Δʁ
ϥΠϒϥϦʹ͓͚ΔυΩϡϝϯτ׆༻ • ੜ͞ΕͨHTMLυΩϡϝϯτ͔ΒREPLʢIRBʣΛىಈͰ͖Δ • ϥΠϒϥϦͷؾʹͳΔػೳΛ͙͢ࢼͤΔ • υΩϡϝϯτʹରԠ͢ΔϝιουΫϥεʹؔ࿈͢Δςετίʔυ͕ ಡΊΔʢࡉ͔͍༷ΛѲͰ͖Δʣ
υΩϡϝϯτ ·ͩਐԽͰ͖Δʂ
·ͱΊ
ָ͍͠υΩϡϝϯςʔγϣϯΛࢦͯ͠ • ֦ுػೳج൫ʹΑΔπʔϧͷRDocͷ౷߹ • υΩϡϝϯςʔγϣϯΛָʹ͢ΔΞΠσΞ • υΩϡϝϯτΛॻ͘͜ͱ͕ใΘΕΔΑ͏ʹͳΔͨΊͷπʔϧͷվળ
େࣄͳ͜ͱ
ະ࣮
Ұ෦ ࣮ۙ
https://www.ruby.or.jp/ja/news/20240821
https://www.ruby.or.jp/ja/news/20241030
࠷ऴใࠂظݶ 20253݄
͕ΜΓ·͢ʂ