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
200
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
Why doesn't Ruby have Boolean class?
okuramasafumi
0
9
My KaigiEffect at RubyKaigi 2025, part 1
okuramasafumi
1
47
Alba: Why, How and What's So Interesting
okuramasafumi
0
400
Why did my proposals get rejected?
okuramasafumi
1
710
A suggestion for the future of RDoc
okuramasafumi
1
390
15 JSON serializers for Ruby
okuramasafumi
2
450
Tech Events, Should We See Them from the Outside or the Inside?
okuramasafumi
1
75
Creating gems 101
okuramasafumi
2
150
How NOT to make your DSL terrible
okuramasafumi
0
640
Other Decks in Programming
See All in Programming
技術的負債で信頼性が限界だったWordPress運用をShifterで完全復活させた話
rvirus0817
1
1.7k
A Gopher's Guide to Vibe Coding
danicat
0
150
DynamoDBは怖くない!〜テーブル設計の勘所とテスト戦略〜
hyamazaki
1
200
[DevinMeetupTokyo2025] コード書かせないDevinの使い方
takumiyoshikawa
2
280
Go製CLIツールをnpmで配布するには
syumai
2
1.2k
WebAssemblyインタプリタを書く ~Component Modelを添えて~
ruccho
1
830
一人でAIプロダクトを作るための工夫 〜技術選定・開発プロセス編〜 / I want AI to work harder
rkaga
12
2.6k
大規模FlutterプロジェクトのCI実行時間を約8割削減した話
teamlab
PRO
0
480
Nuances on Kubernetes - RubyConf Taiwan 2025
envek
0
170
Android 15以上でPDFのテキスト検索を爆速開発!
tonionagauzzi
0
200
プロダクトという一杯を作る - プロダクトチームが味の責任を持つまでの煮込み奮闘記
hiliteeternal
0
460
AIレビュアーをスケールさせるには / Scaling AI Reviewers
technuma
2
190
Featured
See All Featured
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
234
17k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
161
15k
Visualization
eitanlees
146
16k
Designing for humans not robots
tammielis
253
25k
Stop Working from a Prison Cell
hatefulcrawdad
271
21k
It's Worth the Effort
3n
186
28k
Building Better People: How to give real-time feedback that sticks.
wjessup
367
19k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
50
5.5k
Intergalactic Javascript Robots from Outer Space
tanoku
272
27k
Making the Leap to Tech Lead
cromwellryan
134
9.5k
ReactJS: Keep Simple. Everything can be a component!
pedronauck
667
120k
StorybookのUI Testing Handbookを読んだ
zakiyama
30
6k
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݄
͕ΜΓ·͢ʂ