User Directory documentation is confusing and misleading.

[Half-Shot]

73118b6#diff-a9b4f5ce35bb739be9f3fe515413e401R34

This API performs a server-side search over all users registered on the server.

Implies that the search will cover the whole server, including the users I have not met.

It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.

Implies that the search will cover only users I have met, including those from other servers.

From what I can see, the synapse implementation does the latter of the two things but maybe it's a combination of both. Either way, the two sentences seem contradictory to me and I think it warrants further explaining.

As a person reading the spec, I'd assume it would be searching only my local server for users I have met.

[ghost]

It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.

My reading of this says that as soon as you're in a room which is not invite-only, you can be found, even by people not in the room. I agree it could be clearer though.

[Half-Shot]

@Matrixcoffee The statement on it's own makes sense. It's the fact that you've also got "
This API performs a server-side search over all users registered on the server.
" which says something entirely different

[t3chguy]

/me is bad at wording - sorry :(

[maxidorius]

And technically, only synapse perform the search that way, it doesn't have to be done that way.
It can be any algorithm or any policy in effect to decide what will be returned exactly, surely?

[richvdh]

if anyone can suggest better wording, that would be appreciated.

Certainly what synapse does is not necessarily definitive here and details may be up to implementation or policy - so some aspects may be better phrased as recommendations or suggestions in the description.

[Half-Shot]

(I seem to be forever finding GH issues that I have missed)

@maxidor I would very much like for this to define the behavior we should expect. If I write a client that says "this is a list of all known users" I would like for that to be the case. If you want to deviate from a behavior, use a parameter.

[maxidorius]

@Half-Shot then I think you should be very specific about list of known users - known to whom? the user? the sysadmin? the hosting system?
And do you include bridged networks? if not, why? etc.

[t3chguy]

That's made more difficult by even synapse having a config toggle for what that means.