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
130
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
Alba: Why, How and What's So Interesting
okuramasafumi
0
260
Why did my proposals get rejected?
okuramasafumi
1
550
A suggestion for the future of RDoc
okuramasafumi
1
190
15 JSON serializers for Ruby
okuramasafumi
2
250
Tech Events, Should We See Them from the Outside or the Inside?
okuramasafumi
1
53
Creating gems 101
okuramasafumi
1
100
How NOT to make your DSL terrible
okuramasafumi
0
440
オブジェクトしこう
okuramasafumi
2
350
Debugging Alba
okuramasafumi
1
230
Other Decks in Programming
See All in Programming
Djangoにおける複数ユーザー種別認証の設計アプローチ@DjangoCongress JP 2025
delhi09
PRO
4
510
Datadog Workflow Automation で圧倒的価値提供
showwin
1
310
JAWS Days 2025のインフラ
komakichi
1
340
Serverless Rust: Your Low-Risk Entry Point to Rust in Production (and the benefits are huge)
lmammino
1
160
苦しいTiDBへの移行を乗り越えて快適な運用を目指す
leveragestech
0
1.2k
CloudNativePGを布教したい
nnaka2992
0
120
iOSでQRコード生成奮闘記
ktcryomm
2
130
Jasprが凄い話
hyshu
0
180
もう僕は OpenAPI を書きたくない
sgash708
6
1.9k
.NET Frameworkでも汎用ホストが使いたい!
tomokusaba
0
210
Google Cloudとo11yで実現するアプリケーション開発者主体のDB改善
nnaka2992
1
120
楽しく向き合う例外対応
okutsu
0
730
Featured
See All Featured
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
175
52k
The Power of CSS Pseudo Elements
geoffreycrofte
75
5.5k
A designer walks into a library…
pauljervisheath
205
24k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
33
2.8k
Art, The Web, and Tiny UX
lynnandtonic
298
20k
Why Our Code Smells
bkeepers
PRO
336
57k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
32
2.2k
A Modern Web Designer's Workflow
chriscoyier
693
190k
Build your cross-platform service in a week with App Engine
jlugia
229
18k
Agile that works and the tools we love
rasmusluckow
328
21k
A Philosophy of Restraint
colly
203
16k
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݄
͕ΜΓ·͢ʂ