Add module API method to resolve a room alias to a room ID

[buffless-matt]

Description

Addresses #13359.

Pull Request Checklist

• Pull request is based on the develop branch
• Pull request includes a changelog file. The entry should:
  • Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
  • Use markdown where necessary, mostly for code blocks.
  • End with either a period (.) or an exclamation mark (!).
  • Start with a capital letter.
  • Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
• Pull request includes a sign off
• Code style is correct
  (run the linters)

[babolivier]

Could you add a test for this method please? There are several tests already in this class which you can use for inspiration.

[dklimpel]

Could you add a test for this method please? There are several tests already in this class which you can use for inspiration.

And some docs please (https://github.com/matrix-org/synapse/tree/develop/docs/modules).

[buffless-matt]

Could you add a test for this method please? There are several tests already in this class which you can use for inspiration.

@babolivier, added in 83de48b.

[buffless-matt]

Could you add a test for this method please? There are several tests already in this class which you can use for inspiration.

And some docs please (https://github.com/matrix-org/synapse/tree/develop/docs/modules).

@dklimpel, I can see quite a few pre-existing module API methods (e.g. this one) that aren't documented in here. Perhaps those docs are for mainly for callbacks? If you insist on the docs, could you please provide a suggestion for where they should go?

[dklimpel]

I don't have any special ideas. I only see that the documentation is often forgotten and that currently approx. 60 issues are already tagged with documentation.
It doesn't make for acceptance of the system and ecosystem if you have to scroll through the code to get information.
The alternative is to create another issue that deals with the missing documentation.

Probably a new page with all helper functions (e.g. check_push_rule_actions, lookup_room_alias, get_monthly_active_users_by_service) would be useful.

Related to:

• Document how to deploy plugins #8944
• Documentation of the Third Party Event Rules #7954
• Terminology for third-party modules is confusing #12186

[buffless-matt]

@dklimpel I agree that documentation is important. The biggest challenge with documentation (in my opinion) is ensuring that it remains up-to-date (i.e. doesn't go stale). I think docs are less likely to become stale if their canonical source lives closest to the source code that is being documented. Of course it's not always practical to have all documentation in docstrings, but in this case I think the docstring documentation is sufficient.

It doesn't make for acceptance of the system and ecosystem if you have to scroll through the code to get information.

I'd argue:

• Ideally the docstrings should be used to automatically generate documentation and I think this endeavour should be pursued, rather than making copies of documentation.
• While not all use-cases warrant scrolling through code, I think it's good general practice to read (at least once) the code that you haven't written and will depend on (where feasible obviously).

---

Perhaps @babolivier can be the arbiter of this discussion?

[babolivier]

Empirically documentation for the ModuleApi class has always lived in docstrings in the code (and that's what we're linking to in the docs when we do), so having it there in this case is fine. We (the Synapse team) agree that this documentation should be available on the documentation website but we haven't figured out how to automate this yet. There is an ongoing discussion about this here: #10687.

[babolivier]

Mostly lgtm, just a couple of points to clear

[babolivier]

lgtm, thanks! :)