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
110
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
240
Why did my proposals get rejected?
okuramasafumi
1
540
A suggestion for the future of RDoc
okuramasafumi
1
160
15 JSON serializers for Ruby
okuramasafumi
2
220
Tech Events, Should We See Them from the Outside or the Inside?
okuramasafumi
1
48
Creating gems 101
okuramasafumi
1
97
How NOT to make your DSL terrible
okuramasafumi
0
410
オブジェクトしこう
okuramasafumi
2
320
Debugging Alba
okuramasafumi
1
220
Other Decks in Programming
See All in Programming
Swiftコンパイラ超入門+async関数の仕組み
shiz
0
210
Software Architecture
hschwentner
6
2.1k
定理証明プラットフォーム lapisla.net
abap34
1
1.7k
Lottieアニメーションをカスタマイズしてみた
tahia910
0
110
Kubernetes History Inspector(KHI)を触ってみた
bells17
0
190
TokyoR116_BeginnersSession1_環境構築
kotatyamtema
0
100
『GO』アプリ バックエンドサーバのコスト削減
mot_techtalk
0
110
2025.01.17_Sansan × DMM.swift
riofujimon
3
700
Multi Step Form, Decentralized Autonomous Organization
pumpkiinbell
1
520
SRE、開発、QAが協業して挑んだリリースプロセス改革@SRE Kaigi 2025
nealle
3
4k
Amazon Nova Reelの可能性
hideg
0
280
DevinとCursorから学ぶAIエージェントメモリーの設計とMoatの考え方
itarutomy
1
580
Featured
See All Featured
Building Your Own Lightsaber
phodgson
104
6.2k
Adopting Sorbet at Scale
ufuk
74
9.2k
The World Runs on Bad Software
bkeepers
PRO
67
11k
Bootstrapping a Software Product
garrettdimon
PRO
305
110k
A Modern Web Designer's Workflow
chriscoyier
693
190k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
Writing Fast Ruby
sferik
628
61k
How STYLIGHT went responsive
nonsquared
98
5.3k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
45
2.3k
How to Think Like a Performance Engineer
csswizardry
22
1.3k
Side Projects
sachag
452
42k
GitHub's CSS Performance
jonrohan
1030
460k
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݄
͕ΜΓ·͢ʂ