Lesson 19 - Reading Documentation
Preface
We recognize that the PROS for V5 Documentation can be intimidating for those just learning how to program. For this reason, this lesson aims to give you guidance on how to navigate the PROS Documentation.
Getting to the API
Although you can navigate through the PROS website, here is a direct link to the C++ API: https://pros.cs.purdue.edu/v5/api/cpp/index.html
Note: Make sure that the page specifies C++ API. The link should take you to a page that looks something along the lines of this:
As you can see in the image, there is a list with different documentation categories. If we were to generalize the most commonly referenced categories, they are the ones that are bolded.
ADI (TriPort) C++ API -- Old Sensors That Have 3 Wire Ports (Digital and Analog Sensors)
VEX Distance Sensor C++ API -- Commands for the VEX Distance Sensor (released in 2021)
VEX Inertial Sensor C++ -- VEX Inertial Sensor to detect rotation/yaw
LLEMU C++ API -- Commands for the green display you see on the screen
Miscellaneous C++ API -- Includes Commands for Joystick (among others)
Motors C++ API -- All of the commands for the standard pros::Motor
VEX Optical Sensor -- Commands for the VEX Optical Sensor (released in 2021)
VEX Rotation Sensor C++ API -- Commands for the VEX Rotation Sensor (released in 2021)
RTOS Facilities C++ API -- includes documentation on how to delay/sleep/wait and for multi-tasking
Vision Sensor C++ API -- Commands for the Vision Sensor
Fortunately, each one of these sections is standard in their content. For the rest of the lesson, we will be using the Motors C++ API and the Inertial Sensor C++ API as an example to illustrate what we are talking about.
1. In the beginning, each of the API’s will always cover the constructors. This would be how to declare/create this specific electronic or object.
If you click on the constructor, it will take you to a segment of code for both the “Prototype” and an “Example.” The “Prototype” tab requires knowledge of classes, namespaces, virtual functions, etc. Therefore, for newer programmers the “Example” tab will be considerably more useful since it gives a practical example on how to use the function/constructor/command. Here is a comparison of the “Prototype” for Motors and the “Example” Tab.
2. Next each of the sections in the documentation will cover commands. First come action commands. These cause something to occur physically. For example, the “Action Commands” in the Motor API are movement functions.
3. Up next are typically “getter” functions, which get the state of something. In the Motors API, all the “getter” functions are under the “telemetry” branch.
3.1 Finally are “setter” functions which let you modify certain parameters/constants associated with that electronic/object).
4. Enumerations: In this context, enumeration is a fancy word for variable. Don’t worry about this too much, but feel free to read up on Enumerations in C++ further if you please.
5. MAKE SURE TO READ THE API DESCRIPTIONS. THEY ARE OFTEN ENOUGH TO HELP YOU UNDERSTAND. THEY LOOK LIKE THIS:
Summary
When stuck or needing to reference something, use the C++ API. Typically, the constructors are in the beginning and then come the relevant functions. Furthermore, the “Example” code tab is a very valuable resource to reference.
If you take away one thing from this lesson then let it be the following: use the examples tab and the written explanation in the API if you don’t know what something means.