The `ENES100.mission()` needs clearer code and improved documentation

[briandk]

Problem - The mission() function documentation isn't clear

The documentation for ENES100.mission() looks like this:

ENES100ArduinoLibrary/README.md

Lines 98 to 102 in cec8cdc

	Valid calls for **DATA**:
	* `Enes100.mission(CYCLE, x);` *x is the duty cycle percent (ex. 10, 30, 50, 70, 90)*
	* `Enes100.mission(MAGNETISM, MAGNETIC);`
	* `Enes100.mission(MAGNETISM, NOT_MAGNETIC);`

What's not clear is how many arguments (and of what type) each function takes. Does Enes100.mission(CYCLE, x); take one argument x, whose meaning is the duty cycle? Or does it take two arguments? And if it takes two, what types are the arguments?

Also, why should students use the mission() function instead of just printing to the serial monitor directly?

As I show below, confusion over what arguments (and what types) the mission() function takes matters, because the arguments determine which version of mission() gets dispatched

The ENES100.mission() function actually seems to use polymorphic dispatch

Here's one version of the function that takes two ints as arguments:

ENES100ArduinoLibrary/src/VisionSystemClient.cpp

Lines 57 to 65 in cec8cdc

	bool VisionSystemClient::mission(int type, int message) {
	mSerial->write(OP_MISSION);
	mSerial->write(type);
	mSerial->print(message);
	mSerial->write(FLUSH_SEQUENCE, 4);
	mSerial->flush();
	return receive(NULL);
	}

And here's another that takes an int and a char:

ENES100ArduinoLibrary/src/VisionSystemClient.cpp

Lines 76 to 84 in cec8cdc

	bool VisionSystemClient::mission(int type, char message) {
	mSerial->write(OP_MISSION);
	mSerial->write(type);
	mSerial->print(message);
	mSerial->write(FLUSH_SEQUENCE, 4);
	mSerial->flush();
	return receive(NULL);
	}

A user shouldn't have to know which version of the function gets dispatched , but students are getting very confused about how many arguments they're supposed to provide to mission() and what types those arguments should be.

Proposed Solution

We should at least be using syntax-colored fenced code blocks to document function calls.

So,

```ino
ENES100.mission(int type, char message)
```

becomes

ENES100.mission(int type, char message);

Questions

1. Why do we have multiple versions of ENES100.mission()?
2. Why don't students just use a basic print command to print to the serial monitor?
3. Can we implement fenced code blocks in the README to make documentation clearer?

/cc @itsecgary

[itsecgary]

1. There are multiple versions of Enes100.mission() because that is how it was supported in the past. I left these types in here in case we wanted to change anything about mission calls.
2. We have the Enes100.print() and Enes100.println() calls for debug use only. As far as completing an actual run of the course, the Show Debug Messages option at https://enes100.umd.edu/ will be unchecked, which ignores all print() and println() calls by only printing the mission() calls.
3. I can work on the documentation now. I do agree that it is unclear how students should call the mission calls. I made definitions for all of the the mission types Enes100.h as well as for mission values that were not integers.

[itsecgary]

Just updated the documentation. I tried to explain the use of C definitions a little bit. Let me know if there is anything you think I should still change with the documentation. I'll leave this issue up for now. /cc @briandk

[briandk]

@itsecgary Thanks for updating things.

A few things:

1. I'm unclear how changes to the README propagate to the ENES100.umd.edu Libraries website. I made some changes yesterday in 8f7ec3a to update syntax highlighting, but the syntax examples on the Libraries webpage don't show any color.
2. The ENES100.mission() "examples" aren't really examples. We say they're "Valid calls", but they're not. Below is an example:

Enes100.mission(WATER\_TYPE, FRESH\_UNPOLLUTED);

The above code, pasted verbatim, produces this error in the simulator:

g++ -I ./ -o ../environments/361f9c3fe48b4cbaaaffed8167341212/361f9c3fe48b4cbaaaffed8167341212 ../environments/361f9c3fe48b4cbaaaffed8167341212/361f9c3fe48b4cbaaaffed8167341212.cpp ArduinoHelpers.o TankClient.o VisionSystemClient.o
../environments/361f9c3fe48b4cbaaaffed8167341212/361f9c3fe48b4cbaaaffed8167341212.cpp:18:37: error: stray ‘\’ in program
  Enes100.mission(__LINE__ - 2, WATER\_TYPE, FRESH\_UNPOLLUTED);
                                     ^
../environments/361f9c3fe48b4cbaaaffed8167341212/361f9c3fe48b4cbaaaffed8167341212.cpp:18:50: error: stray ‘\’ in program
  Enes100.mission(__LINE__ - 2, WATER\_TYPE, FRESH\_UNPOLLUTED);
                                                  ^

The examples need to be real examples that would actually compile as written.

[itsecgary]

The thing with the backslashes was basically just a typo. I put those there to get rid of italicization, but I ended up putting them in code blocks instead. I tried changing ino to arduino and it seems like the syntax highlighting doesn't like to work for either.

Enes100.mission(WATER\_TYPE, FRESH\_UNPOLLUTED);

[briandk]

@itsecgary So, how (if at all) does http://enes100.umd.edu/libraries/ get generated from the README.md in this repo?

[itsecgary]

The Vision System website is formed from a static website generator called Jekyll and some of the past LTFs had created a Jekyll format for being able to point to a GitHub repository and extract the main README.md from it. So we use the repositories for documentation as well as for source. Hopefully that makes some sense of how the website gets the data here.