Add docs for the plugin API #87
Conversation
Ho1yShif
left a comment
Ho1yShif
left a comment
There was a problem hiding this comment.
Great job on this! Can't wait to see what developers do with it
|
|
||
| ## Accessing the API | ||
|
|
||
| Plugins and command bar all share the same module cache, which allows us to expose the API through a ModuleScript located at `game.Rojo`. Using the name `"Rojo"` is easy to remember and follows branding. Once you've required Rojo, the API will be located at `Rojo.API`. For example: |
There was a problem hiding this comment.
| Plugins and command bar all share the same module cache, which allows us to expose the API through a ModuleScript located at `game.Rojo`. Using the name `"Rojo"` is easy to remember and follows branding. Once you've required Rojo, the API will be located at `Rojo.API`. For example: | |
| Plugins and command bar all share the same module cache, which allows us to expose the API through a ModuleScript located at `game.Rojo`. Using the name `"Rojo"` is easy to remember and is recommended. Once you've required Rojo, the API will be located at `Rojo.API`. For example: |
Feels weird to mention branding in docs.
There was a problem hiding this comment.
This phrasing still reads a little oddly imo - maybe we should simply say "We chose the name Rojo because it is easy to remember," or alternatively, strike this sentence entirely? I don't think it's particularly necessary for the sentiment we're trying to get across here
| }) | ||
| ``` | ||
|
|
||
|  |
There was a problem hiding this comment.
This asset is not located in the PR! We should try to keep things local to avoid link rot.
| ```Lua | ||
| Rojo.API:ConnectAsync(host: string?, port: string?): void | ||
| ``` | ||
| Attempts to connect Rojo to the given host and port. Same behavior as the user clicking the Connect button (sync locking, etc., all behave the same). |
There was a problem hiding this comment.
Given how messy the meaning of Async is in Roblox, it might be worth mentioning that this (and any other async API) yield and what they yield on. It's a small QoL thing for implementors to know.
| ```Lua | ||
| Rojo.API:GetSetting(setting: string): any | ||
| ``` | ||
| Returns the value of the given setting. |
There was a problem hiding this comment.
Do we want to list the settings here?
docs/headless-api.md
Outdated
| ``` | ||
| Sends a Rojo notification that indicates it comes from a third-party plugin. Returns a function that dismisses the notification. | ||
|
|
||
|  |
There was a problem hiding this comment.
Same concern with the asset link here.
| Returns the user's chosen host and port, even if not actively connected to it. | ||
|
|
||
| ```Lua | ||
| Rojo.API:CreateApiContext(baseUrl: string): ApiContext |
There was a problem hiding this comment.
How do we want to approach documenting ApiContext? It's an implementation detail right now, but if we expose this it needs to be versioned and documented.
| ```Lua | ||
| Rojo.API:CreateApiContext(baseUrl: string): ApiContext | ||
| ``` | ||
| Returns a new ApiContext using the given baseUrl. Useful for complex use cases that directly interface with Rojo endpoints. |
There was a problem hiding this comment.
| Returns a new ApiContext using the given baseUrl. Useful for complex use cases that directly interface with Rojo endpoints. | |
| Returns a new `ApiContext` using the given baseUrl. Useful for complex use cases that directly interface with Rojo endpoints. |
| ```Lua | ||
| Rojo.API.Version: {number} | ||
| ``` | ||
| The Rojo plugin version. (Example: `{7, 2, 1}`) |
There was a problem hiding this comment.
Wow, we've been sitting on this PR for too long! Sorry, haha.
| ```Lua | ||
| Rojo.API.ProtocolVersion: number | ||
| ``` | ||
| The Rojo plugin's protocol version. |
There was a problem hiding this comment.
This is, as far as I know, the only mention of protocol version in the docs. Do we want to elaborate on it a bit?
| ```Lua | ||
| Rojo.API.Connected: boolean | ||
| ``` | ||
| Whether Rojo is currently connected to a serve session. |
There was a problem hiding this comment.
| Whether Rojo is currently connected to a serve session. | |
| Whether Rojo is currently connected to a server. |
Let's try to avoid things that invite questions like "serve session".
It's obvious to you and me what that means, but it seems like the sort of thing we'll get questions about.
There was a problem hiding this comment.
I think it'd be good to err on the side of specificity:
"Whether the Roblox Studio plugin is currently connected to a Rojo server"
Perhaps a little extreme, but the point stands, lol
5 participants
This is waiting until rojo-rbx/rojo#639 is released, but reviews for grammar and clarity are welcome!
You can read the rendered version here:
https://github.com/boatbomber/rojo.space/blob/headless-api-docs/docs/headless-api.md