Add some documentation

README.md

+# Fixer for Matrix's Facebook Messenger puppet bridge
+
+I'm using the [Matrix↔️Facebook Messenger puppet bridge](https://github.com/matrix-hacks/matrix-puppet-facebook) to talk with my friends on Facebook using [Riot](https://riot.im) plugged to my [Matrix](https://matrix.org) homeserver.
+
+When I'm having a 1:1 chat with a Facebook friend, the bridge creates a with the friend, the appservice's bot and myself. Because of that, and also because it doesn't automatically set the room's avatar and name, I have troubles identifying what's happening in that room.
+
+This small tool will take the local part of the room ID created by the Matrix↔️Facebook Messenger bot once the friend has joined it, identify the friend, and grab their avatar and display name to set the room's.
+
+**Note: I'm not shaming anyone here, as the bridge is currently still in development. This is totally a temporary solution.**
+
+## Install
+
+You'll first need a Go install, and [gb](https://getgb.io/):
+
+```
+go get github.com/constabulary/gb/...
+```
+
+Then clone this repo on your computer (or server), walk into it, install its dependencies and build it:
+
+```
+git clone https://github.com/babolivier/matrix-puppet-facebook-1to1-fixer
+cd matrix-puppet-facebook-1to1-fixer
+gb vendor restore
+gb build
+```
+
+## Configure
+
+An example configuration is located in the [config.sample.yaml](config.sample.yaml) file.
+
+Copy it somewhere, and edit it accordingly with the key's comments.
+
+## Run
+
+You have to run this tool manually for each room you want to edit.
+
+You can run this tool by typing
+
+```
+./bin/fixer --room-id-localpart ROOM_ID_LOCALPART
+```
+
+where `ROOM_ID_LOCALPART` is the room's ID's localpart (which usually looks like something like `ZUFHhmRzEyUdzljKRz`).
+
+If you moved your configuration file to a different path than `./config.yaml`, you can specify the configuration file's path by appending the `--config CONFIG_PATH` to your command, where `CONFIG_PATH` is the path to your configuration file.
+
+## Stuff it doesn't do
+
+Because it's not supported by [gomatrix](https://github.com/matrix-org/gomatrix) yet, this tool won't set the room as direct chat, nor will it change its push notification settings. These features will be added as soon as gomatrix supports them.

config.sample.yaml

+# Matrix-related settings
+matrix:
+  # The full URL of the homeserver to contact.
+  homeserver_url: https://matrix.org
+  # The server name of the homeserver to contact.
+  server_name: matrix.org
+  # The local part from the bridge user's Matrix ID. In the example shown in this
+  # sample file, the user's Matrix ID is @Alice:matrix.org.
+  localpart: Alice
+  # The bridge user's access token.
+  access_token: ACCESS_TOKEN

src/config/config.go

 	"gopkg.in/yaml.v2"
 )
 
+// Config represents the full configuration.
 type Config struct {
 	Matrix MatrixConfig `yaml:"matrix"`
 }
 
+// MatrixConfig represents the Matrix part of the configuration.
 type MatrixConfig struct {
+	// HomeserverURL is the full URL of the homeserver to contact
+	// (e.g. https://matrix.org/).
 	HomeserverURL string `yaml:"homeserver_url"`
-	ServerName    string `yaml:"server_name"`
-	Localpart     string `yaml:"localpart"`
-	AccessToken   string `yaml:"access_token"`
+	// ServerName is the server name of the homeserver to contact
+	// (e.g. matrix.org)0.
+	ServerName string `yaml:"server_name"`
+	// Localpart is the local part from the bridge user's Matrix ID (e.g. Alice).
+	Localpart string `yaml:"localpart"`
+	// AccessToken is the bridge user's access token.
+	AccessToken string `yaml:"access_token"`
 }
 
+// Parse reads the file located at the provided path then proceeds to create and
+// fill in a Config instance.
 func Parse(path string) (cfg *Config, err error) {
 	cfg = new(Config)
 
+	// Load the content from the configuration file.
 	content, err := ioutil.ReadFile(path)
 	if err != nil {
 		return
 	}
 
+	// Parse the YAML content from the configuration file.
 	err = yaml.Unmarshal(content, cfg)
 	return
 }

src/fixer/main.go

 	"flag"
 	"fmt"
 	"os"
+	"regexp"
 
 	"config"
 
 
 // Fixed variables
 var (
-	// ErrEmptyRoomID is fired if no room ID localpart has been provided, and is
-	// followed by the command's usage.
-	ErrEmptyRoomID = fmt.Errorf("The room ID localpart cannot be empty")
+	// ErrRoomIDEmptyOrInvalid is fired if no room ID localpart has been provided
+	// or is invalid, and is followed by the command's usage.
+	ErrRoomIDEmptyOrInvalid = fmt.Errorf("The room ID localpart is either empty or invalid")
 	// ErrInvalidRoomMembersNb is fired if the number of joined members in the
 	// room isn't 3 (i.e.: the user, their friend, and the Facebook bot).
 	ErrInvalidRoomMembersNb = fmt.Errorf("Invalid number of members in the room: either the friend hasn't joined yet, or there's more than one friend in the room")
 	InfoNameUpdated = "Room's name updated"
 	// InfoProcessIsOver is displayed once the whole process is over, just before
 	// exiting.
-	InfoProcessIsOver = "The room has been fully updated. Don't forget to mark it as direct chat in Riot, and to edit its push rules."
+	InfoProcessIsOver = "The room has been fully updated. Don't forget to mark it as direct chat in Riot, and to edit its notification rules."
 )
 
 // Command line flags
 var (
-	localpart  = flag.String("room-id-localpart", "", "Room ID localpart")
+	localpart  = flag.String("room-id-localpart", "", "Room ID localpart (i.e. 'ZUFHhmRzEyUdzljKRz')")
 	configFile = flag.String("config", "config.yaml", "Configuration file")
 )
 
 
 	flag.Parse()
 
-	if len(*localpart) == 0 {
-		logrus.Error(ErrEmptyRoomID)
+	// We need the room ID's localpart to be non-empty and only composed of letters.
+	roomIDLocalpartRgxp := regexp.MustCompile("^[a-zA-Z]+")
+	if len(*localpart) == 0 || !roomIDLocalpartRgxp.Match([]byte(*localpart)) {
+		logrus.Error(ErrRoomIDEmptyOrInvalid)
 		flag.Usage()
 		os.Exit(1)
 	}
 
+	// Load the configuration from the configuration file.
 	cfg, err := config.Parse(*configFile)
 	if err != nil {
 		panic(err)
 	}
 
+	// Compute the room's ID along with the current user's.
 	roomID := fmt.Sprintf("!%s:%s", *localpart, cfg.Matrix.ServerName)
 	userID := fmt.Sprintf("@%s:%s", cfg.Matrix.Localpart, cfg.Matrix.ServerName)
 
+	// Load the Matrix client from configuration data.
 	cli, err := gomatrix.NewClient(cfg.Matrix.HomeserverURL, userID, cfg.Matrix.AccessToken)
 	if err != nil {
 		logrus.Panic(err)
 	}
 
+	// Retrieve the list of joined members in the room.
 	membersResp, err := cli.JoinedMembers(roomID)
 	if err != nil {
 		logrus.Panic(err)
 	}
 
+	// Retrieve the current user's own display  name.
 	displayNameResp, err := cli.GetOwnDisplayName()
 	if err != nil {
 		logrus.Panic(err)
 	}
 
+	// Check if the number of joined members is three, as it should be with a
+	// 1:1 puppeted chat (the current user, their friend, and the AS bot).
 	if len(membersResp.Joined) != 3 {
 		logrus.Error(ErrInvalidRoomMembersNb)
 		os.Exit(1)
 	}
 
+	// Iterate over the slice of joined members.
 	var avatarURL, displayName string
 	for _, member := range membersResp.Joined {
+		// The friend should be the only joined member who has a display name set
+		// which isn't the same as the current user's.
 		if member.DisplayName != nil && *(member.DisplayName) != displayNameResp.DisplayName {
 			displayName = *(member.DisplayName)
+			// If there's also an avatar set for the friend, use it.
 			if member.AvatarURL != nil {
 				avatarURL = *(member.AvatarURL)
 			}
 		"avatar_url":   avatarURL,
 	}).Info("Found the friend")
 
+	// If the avatar has been found, set it as the room's avatar using a
+	// m.room.avatar state event.
 	if len(avatarURL) > 0 {
 		if _, err := cli.SendStateEvent(
 			roomID,
 		}
 		logrus.Info(InfoAvatarUpdated)
 	} else {
+		// Else print a warning so the user can see it clearly.
 		logrus.Warn(WarnNoAvatar)
 	}
 
+	// If the display name has been found, set it as the room's name using a
+	// m.room.name state event. This condition shouldn't be necessary, but heh,
+	// at least that might cover a potential regression from the bridge.
 	if len(displayName) > 0 {
 		if _, err := cli.SendStateEvent(
 			roomID,
 		}
 		logrus.Info(InfoNameUpdated)
 	} else {
+		// Else print a warning so the user can see it clearly.
 		logrus.Warn(WarnNoDisplayName)
 	}
 
+	// Print a shiny message telling the user the process is over, but it's up
+	// to them to set the room as a direct chat and to update the room's push
+	// notification settings, since that's not supported by gomatrix.
 	logrus.Info(InfoProcessIsOver)
 }