Draft: Preliminary work on JSON-RPC docs #600

dtinth · 2021-09-07T19:49:31Z

Work in progress

Corresponding Jamulus PR: jamulussoftware/jamulus#1975

Does this need translation?

Yes
No

Changes

gilgongo · 2021-09-08T07:27:03Z

wiki/en/JSON-RPC.md

+---
+
+# JSON-RPC interface
+


As I assume this page will grow in time (and is already quite extensive), you may want to add a table of contents.

Suggested change

{:.no_toc}

This manual documents the JSON-RPC-based protocol by which you can control the Jamulus client and server.

<details markdown="1">

<summary>Table of contents</summary>

* TOC

{:toc}

</details>

@gilgongo I am thinking about whether we need an extensive documentation for JSON-RPC at all…

My concern is that this would double the work required to make changes to the JSON-RPC interface. First you would need to make changes in jamulus project, and then you would need to document the method here in jamuluswebsite.

I think that adds substantial maintenance burden. I want to avoid having to make changes to 2 repositories and filing 2 PRs. So, upon second thought, I am thinking of doing either of these:

Point the reader to read clientrpc.cpp and serverrpc.cpp. Since the code is quite self-documenting already, it may be a redundant to have an English documentation at all.

Add some code comments directly in clientrpc.cpp and serverrpc.cpp and create a Python script to generate a Markdown documentation based on these comments (e.g. tools/generate_rpc_docs.py). The documentation would live directly in jamulus repository, e.g. RPC.md, and jamuluswebsite would just link there. Maybe some GitHub Actions could be created to ensure that this documentation is up-to-date. This would also lets reader view the documentation of a specific release.

The comment might look like this:

/* For notifications */ /// @rpc_notification jamulusclient/clientListReceived /// @brief Emitted when the client list is received. /// @param {array} params.clients - The client list. /// @param {number} params.clients[*].id - The channel ID. /// @param {string} params.clients[*].name - The musician’s name. /// @param {string} params.clients[*].skillLevel - The musician’s skill level (beginner, intermediate, expert, or null). /// @param {number} params.clients[*].countryId - The musician’s country ID (see QLocale). /// @param {string} params.clients[*].city - The musician’s city. /// @param {number} params.clients[*].instrumentId - The musician’s instrument ID (see CInstPictures::GetTable). /* For methods */ /// @rpc_method jamulusclient/setSkillLevel /// @brief Sets your skill level. /// @param {string} params.skillLevel - The new skill level (beginner, intermediate, expert, or null). /// @result {string} result - Always "ok".

Suggestions or opinions?

I'm not qualified to say, but if it's self-documenting, then less work is always better/safer.

Could we add a more extensive documentation to the file (md table like here and then link the comment from here)? I don’t think people should be forced to read the code. But they can of course read comments - although that’s not optimal (consistency, style) but ok for an experimental feature.

We should also consider the audience of this documentation: It will be developers (not necessarily Jamulus developers or C++ developers). They should already be familiar with reading code or at least comments in the code. I like the idea of having a single place to handle both the code and the directly related docs.

I think we should still keep the first part in the "wiki" (everything including the Example paragraph?), put the method documentation right next to the code and link from the wiki page to the code.

ignotus666 · 2021-09-08T07:34:41Z

Are we going to translate this? It's very technical, and I'd assume anyone using it would be familiar with the terminology in English, but I'll go with the consensus. If we're not, it should go in wiki/en-no-translate/.

gilgongo · 2021-09-08T08:44:30Z

I was assuming we would (I'd actually checked the box on behalf of @dtinth), but if not then the adopted convention is that we'd not put it not on the website but in an .md file in the main repo I think? I didn't know about wiki/en-no-translate/ though!

ignotus666 · 2021-09-08T09:15:22Z

The reason I raise the issue of translation is that it contains a lot of vocabulary that is very technical and specific, which I'm not entirely sure has translations that are commonly used in different languages. I'm not a programmer, but as English is effectively the lingua franca for programming, translations heavy in technical terms may even be harder to understand than the original.

Yes, wiki/en-no-translate/ is where files that don't get translated go, so the .po folders don't get cluttered with unnecessary files. Links to them work exactly the same as to the files in wiki/en/ (i.e., you don't need to specifiy the en-no-translate path).

gilgongo · 2021-09-08T10:01:26Z

OK in that case we can just put it in wiki/en-no-translate/ and it can be on the website.

ignotus666 · 2021-09-08T10:11:36Z

It should be moved there before merging though, otherwise it's going to create a bunch of unwanted .po files. Tagging @dtinth

If other @jamulussoftware/translators want to chime in though that would be great.

gilgongo · 2021-09-08T10:47:14Z

Oh BTW OT but just seen this line in _config.yml

exclude_from_localization: ["assets", "images", "css", "README.md", "manifest.json", "humans.txt", "sitemap.xml", "robots.txt", "404.html", "CNAME", "LICENSE.md"]

Is there a reason wiki/en-no-translate/ isn't listed there?

(Also notice that the site variable seems to have been removed - anyone know why?)

ignotus666 · 2021-09-08T14:20:57Z

I suppose wiki/en-no-translate/ could go in there, yes. As 'site' gets prepended with an underscore (_site) it doesn't get included in the site at all, so needn't be included in the list. That's my guess anyway.

dtinth · 2021-09-08T18:49:40Z

@ignotus666

The reason I raise the issue of translation is that it contains a lot of vocabulary that is very technical and specific, which I'm not entirely sure has translations that are commonly used in different languages. I'm not a programmer, but as English is effectively the lingua franca for programming, translations heavy in technical terms may even be harder to understand than the original.

I totally agree... I will move this to wiki/en-no-translate.

ann0see · 2022-02-15T23:05:34Z

Going to re-open this. @dtinth @gilgongo I raised the question if this should go to the KB or not

ann0see · 2022-02-15T23:16:27Z

Suggestion:

Add a short document to the wiki linking to the jsonrpc code file
Add a well formatted documenting comment in the code
Link the comment from the website

gilgongo · 2022-02-16T07:51:05Z

See my comment on jamulussoftware/jamulus#1975 (comment) - I'm note sure I underand how this PR relates to that one.

dtinth · 2022-02-16T13:34:27Z

@ann0see @gilgongo @hoffie My original plan was to put the documentation in jamulus repo itself, e.g. in JSON-RPC.md, so that its documentation evolves alongside the codebase (similar to COMPILING.md) — that's why this PR was previously closed. I would rather not have to submit PRs to 2 different projects to update them. What do you think?

gilgongo · 2022-02-16T13:39:46Z

@ann0see @gilgongo @hoffie My original plan was to put the documentation in jamulus repo itself, e.g. in JSON-RPC.md, so that its documentation evolves alongside the codebase (similar to COMPILING.md)

Yes, I think the "rule of thumb" is that if the information is aimed at developers messing with "code", then it goes into the repo (like you say, as COMPILING.md is). If it's to do with the "end usage" of Jamulus (so in this case what the effect of turning on the RPC option is, and some basic info on how to use it), then it's on the website (AKA "the wiki", although I'm not sure why we call it that).

hoffie · 2022-02-16T15:51:30Z

Yes, sounds good to me. End-user-relevant things (CLI option, pointer to deeper docs) here in jamuluswebsite, deeper docs right next to (or even -- in the form of comments -- in) the code.

ann0see · 2022-02-16T16:33:46Z

Ok. So next steps:

Add a short entry to the website "we support JSON-RPC and please see the following comment in the code for available options" and CLI documentation
Document all methods in the code.

ann0see · 2022-02-16T16:34:34Z

Closing

Preliminary work on JSON-RPC docs

a8a9f1b

dtinth mentioned this pull request Sep 7, 2021

JSON-RPC interface to control client and server jamulussoftware/jamulus#1975

Merged

13 tasks

Link to source files

78cd438

gilgongo reviewed Sep 8, 2021

View reviewed changes

gilgongo deleted the branch jamulussoftware:next-release October 23, 2021 16:50

gilgongo closed this Oct 23, 2021

ann0see reopened this Feb 15, 2022

ann0see closed this Feb 16, 2022

+ {:.no_toc}
+This manual documents the JSON-RPC-based protocol by which you can control the Jamulus client and server.
+<details markdown="1">
+<summary>Table of contents</summary>
+* TOC
+ {:toc}
+</details>

Draft: Preliminary work on JSON-RPC docs #600

Draft: Preliminary work on JSON-RPC docs #600

Uh oh!

Conversation

dtinth commented Sep 7, 2021 • edited by gilgongo Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Work in progress

Does this need translation?

Changes

Uh oh!

gilgongo Sep 8, 2021

Choose a reason for hiding this comment

Uh oh!

dtinth Sep 8, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gilgongo Sep 8, 2021

Choose a reason for hiding this comment

Uh oh!

ann0see Feb 15, 2022

Choose a reason for hiding this comment

Uh oh!

hoffie Feb 16, 2022

Choose a reason for hiding this comment

Uh oh!

ignotus666 commented Sep 8, 2021

Uh oh!

gilgongo commented Sep 8, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ignotus666 commented Sep 8, 2021

Uh oh!

gilgongo commented Sep 8, 2021

Uh oh!

ignotus666 commented Sep 8, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gilgongo commented Sep 8, 2021

Uh oh!

ignotus666 commented Sep 8, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dtinth commented Sep 8, 2021

Uh oh!

ann0see commented Feb 15, 2022

Uh oh!

ann0see commented Feb 15, 2022

Uh oh!

gilgongo commented Feb 16, 2022

Uh oh!

dtinth commented Feb 16, 2022

Uh oh!

gilgongo commented Feb 16, 2022

Uh oh!

hoffie commented Feb 16, 2022

Uh oh!

ann0see commented Feb 16, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ann0see commented Feb 16, 2022

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dtinth commented Sep 7, 2021 •

edited by gilgongo

Loading

dtinth Sep 8, 2021 •

edited

Loading

gilgongo commented Sep 8, 2021 •

edited

Loading

ignotus666 commented Sep 8, 2021 •

edited

Loading

ignotus666 commented Sep 8, 2021 •

edited

Loading

ann0see commented Feb 16, 2022 •

edited

Loading