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
180
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
38
Alba: Why, How and What's So Interesting
okuramasafumi
0
370
Why did my proposals get rejected?
okuramasafumi
1
660
A suggestion for the future of RDoc
okuramasafumi
1
310
15 JSON serializers for Ruby
okuramasafumi
2
360
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
560
オブジェクトしこう
okuramasafumi
2
450
Other Decks in Programming
See All in Programming
Kotlin エンジニアへ送る:Swift 案件に参加させられる日に備えて~似てるけど色々違う Swift の仕様 / from Kotlin to Swift
lovee
1
260
来たるべき 8.0 に備えて React 19 新機能と React Router 固有機能の取捨選択とすり合わせを考える
oukayuka
2
870
AIプログラマーDevinは PHPerの夢を見るか?
shinyasaita
1
170
Node-RED を(HTTP で)つなげる MCP サーバーを作ってみた
highu
0
110
生成AIコーディングとの向き合い方、AIと共創するという考え方 / How to deal with generative AI coding and the concept of co-creating with AI
seike460
PRO
1
340
Java on Azure で LangGraph!
kohei3110
0
170
iOSアプリ開発で 関数型プログラミングを実現する The Composable Architectureの紹介
yimajo
2
220
童醫院敏捷轉型的實踐經驗
cclai999
0
200
プロダクト志向なエンジニアがもう一歩先の価値を目指すために意識したこと
nealle
0
110
Composerが「依存解決」のためにどんな工夫をしているか #phpcon
o0h
PRO
1
240
CursorはMCPを使った方が良いぞ
taigakono
1
190
Select API from Kotlin Coroutine
jmatsu
1
190
Featured
See All Featured
For a Future-Friendly Web
brad_frost
179
9.8k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
2.9k
Practical Tips for Bootstrapping Information Extraction Pipelines
honnibal
PRO
20
1.3k
How STYLIGHT went responsive
nonsquared
100
5.6k
A Modern Web Designer's Workflow
chriscoyier
694
190k
Connecting the Dots Between Site Speed, User Experience & Your Business [WebExpo 2025]
tammyeverts
5
230
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
48
2.8k
Optimizing for Happiness
mojombo
379
70k
Mobile First: as difficult as doing things right
swwweet
223
9.7k
Into the Great Unknown - MozCon
thekraken
39
1.9k
Bash Introduction
62gerente
614
210k
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݄
͕ΜΓ·͢ʂ