Docs M2 #373

Cam0Cow · 2023-12-02T16:25:33Z

Quality Assurance Checklist

To make reviews more efficient, please make sure the software feature meets the following standards and check everything off that meets the quality check. Once everything has been checked, the assigned reviewers will begin the review process. Edit this description to check off the list.

There are exceptions with all guidelines. As long as your decisions are justified, then you are good! Contact the reviewers or the leads about any exceptions.

Requirements

Things to Consider

Even if the above are checked, is this the best way of writing my code?
- It's possible to write code that works, but are there ways to make code more efficient?

… docs

IshDeshpa · 2023-12-19T07:46:16Z

Task linked: CU-868680632 Update Documentation for M2.0

…ps entirely

…thin the source code, and will be generated using Doxygen. This will allow us to keep the documentation contained within the source code, and will make it easier to keep the documentation up to date. Transition process has already started.

NathanielDelgado

Delete the brief and def flags in the docs because they are unnecessary. Sometimes you might want to use brief but not always if there is not much detail to begin with

Reorganize header and source file doxygen comments to have this placement and level of detail

Add the copywrite back

Apps/Inc/SendTritium.h

aidenmadaffri · 2024-01-10T13:48:38Z

Getting an error on the build of the docs:

no theme named 'sphinx_book_theme' found (missing theme.conf?)
make[1]: *** [Makefile:19: html] Error 2
make[1]: Leaving directory '/home/aiden/LHR/Controls/Docs'
make: *** [Makefile:45: docs] Error 2

This was tested on a fresh Ubuntu install and pull of the repo. Install script from Embedded Sharepoint was ran without any apparent errors.

NathanielDelgado · 2024-01-10T13:51:48Z

Getting an error on the build of the docs:
no theme named 'sphinx_book_theme' found (missing theme.conf?)
make[1]: *** [Makefile:19: html] Error 2
make[1]: Leaving directory '/home/aiden/LHR/Controls/Docs'
make: *** [Makefile:45: docs] Error 2
This was tested on a fresh Ubuntu install and pull of the repo. Install script from Embedded Sharepoint was ran without any apparent errors.

@aidenmadaffri it is telling you you need to install a theme for sphinx to display. This is the theme that is used to generate the HTML documents. You can resolve this using pip install sphinx_book_theme. However, this should be fixed in the install script so maybe make an issue ticket for that? @IshDeshpa

aidenmadaffri · 2024-01-10T13:58:59Z

Getting an error on the build of the docs:
no theme named 'sphinx_book_theme' found (missing theme.conf?)
make[1]: *** [Makefile:19: html] Error 2
make[1]: Leaving directory '/home/aiden/LHR/Controls/Docs'
make: *** [Makefile:45: docs] Error 2
This was tested on a fresh Ubuntu install and pull of the repo. Install script from Embedded Sharepoint was ran without any apparent errors.
@aidenmadaffri it is telling you you need to install a theme for sphinx to display. This is the theme that is used to generate the HTML documents. You can resolve this using pip install sphinx_book_theme. However, this should be fixed in the install script so maybe make an issue ticket for that? @IshDeshpa

This resolves the issue, but yes it should be fixed in the install script.

Apps/Inc/ReadTritium.h

aidenmadaffri

Very clear explanation of all the files and their functions. This will be an excellent resource to reference.

KnockbackNemo

Just a few small proofreading suggestions to support all the great work already done.

Apps/Inc/ReadCarCAN.h

Apps/Inc/ReadTritium.h

Apps/Inc/SendCarCAN.h

KnockbackNemo · 2024-01-11T08:06:00Z

BSP/STM32F413/Src/BSP_GPIO.c

@@ -83,11 +85,10 @@ uint8_t BSP_GPIO_Read_Pin(port_t port, uint16_t pinmask){
 /**
 * @brief   Writes data to a specified pin
 * @param   port The port to write to
- * @param   pin The pin to write to 
+ * @param   pinmask Mask from stm header file that says which pin to write too


Suggested change

* @param pinmask Mask from stm header file that says which pin to write too

* @param pinmask Mask from stm header file that says which pin to write to

KnockbackNemo · 2024-01-11T08:06:05Z

BSP/STM32F413/Src/BSP_UART.c

- * @param   str : pointer to buffer with data to send.
- * @param   len : size of buffer
- * @param   usart : which usart to read from (2 or 3)
+ * @brief   Transmits data to through a specific 


Suggested change

* @brief Transmits data to through a specific

* @brief Transmits data through a specific

KnockbackNemo · 2024-01-11T08:09:18Z

Docs/source/index.rst

-
-   Overview/Hardware
-   Overview/Software
+To actually build the documentation, run ``make docs``. The resulting ``build/html/index.html`` can then be viewed in any browser. When your pull request is merged into the master branch, the documentation changes should be automatically visible on this website.


If we're recommending the extension, then we could consider mentioning it here too

Suggested change

To actually build the documentation, run ``make docs``. The resulting ``build/html/index.html`` can then be viewed in any browser. When your pull request is merged into the master branch, the documentation changes should be automatically visible on this website.

To actually build the documentation, run ``make docs``. The resulting ``build/html/index.html`` can then be viewed in any browser or in the editor using this [VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) by navigating to the Controls/Docs/build/html directory. When your pull request is merged into the master branch, the documentation changes should be automatically visible on this website.

KnockbackNemo · 2024-01-11T08:09:41Z

Drivers/Inc/CANbus.h

+ * @brief   Reads a CAN message from the CAN hardware and returns it to the provided pointers
+ * @param   data 		where to store the received message
+ * @param   blocking 	Whether or not this read should be blocking
+ * @param   bus 		The bus to use, either be CARCAN or MOTORCAN


Suggested change

* @param bus The bus to use, either be CARCAN or MOTORCAN

* @param bus The bus to use, can either be CARCAN or MOTORCAN

KnockbackNemo · 2024-01-11T08:09:51Z

Drivers/Inc/Minions.h

- * @param status 
- * @return true is fail (wrote to an input)
- * @return false is success (wrote to an output)
+ * @param pin the pint to read


Suggested change

* @param pin the pint to read

* @param pin the pin to read

diyarajon

Looks great!

Apps/Src/SendCarCAN.c

diyarajon · 2024-01-11T00:27:54Z

BSP/STM32F413/Src/BSP_ADC.c

+ * @brief   Provides the ADC value of the channel at the specified index
+ * @param   hardwareDevice pedal enum that represents the specific device
+ * @return  Raw ADC value without conversion
+ */ 
 int16_t BSP_ADC_Get_Value(ADC_t hardwareDevice) {


For future possible change: renaming it BSP_ADC_Get_Raw_Value. To differentiate between this function and the one that returns Millivoltage.

Apps/Inc/SendTritium.h

diyarajon · 2024-01-13T19:29:52Z

Apps/Inc/common.h

@@ -1,11 +1,7 @@
 /**
- * @copyright Copyright (c) 2018-2023 UT Longhorn Racing Solar
 * @file common.h
 * @brief 


Is a brief needed here?

diyarajon · 2024-01-13T19:30:04Z

Apps/Inc/fifo.h

@@ -1,11 +1,7 @@
 /**
- * @copyright Copyright (c) 2018-2023 UT Longhorn Racing Solar
 * @file fifo.h
 * @brief 


Apps/Src/SendTritium.c

diyarajon · 2024-01-13T20:56:27Z

BSP/Inc/BSP_CAN.h

+ * @pre     The data parameter must be at least 8 bytes or hardfault may occur.
+ * @param   id : pointer to store id of the message that was received.
+ * @param   data : pointer to store data that was received. Must be 8bytes or bigger.
+ * @return  ERROR if nothing was received so ignore id and data that was received. SUCCESS indicates data was received and stored.


Suggested change

* @return ERROR if nothing was received so ignore id and data that was received. SUCCESS indicates data was received and stored.

* @return ERROR if nothing was received, ignore id and data that was received. SUCCESS indicates data was received and stored.

diyarajon · 2024-01-13T21:23:31Z

Docs/source/Apps/ErrorHandling.rst

+===========
+All OS functions return an error code whose value should immediately be checked by a call to ``assertOSError``. The Controls system cannot run without a properly functioning OS, so any OS error is critical and nonrecoverable. Thus, when an OS function returns an error code that is not ``OS_ERR_NONE``,  the assertion will fail, and the following steps will occur:
+    #. If in DEBUG mode, the file and line of the failed assertion will be printed
+    #. The Array Bypass-Precharge Contactor and Motor Bypass-Precharge Contactor will open


Suggested change

#. The Array Bypass-Precharge Contactor and Motor Bypass-Precharge Contactor will open

#. The Array Precharge-Bypass Contactor and Motor Precharge-Bypass Contactor will open

diyarajon · 2024-01-13T21:26:12Z

Docs/source/Apps/ErrorHandling.rst

+The errors asserted by applications include
+
+* :doc:`ReadTritium <ReadTritium>`: Motor controller errors
+    * Errors sent from the motor controller are asserted by ReadTritium. These are typically nonrecoverable, with the exception of the motor watchdog and hall sensor errors.


Suggested change

* Errors sent from the motor controller are asserted by ReadTritium. These are typically nonrecoverable, with the exception of the motor watchdog and hall sensor errors.

* Errors sent from the motor controller are asserted by ReadTritium. These are typically nonrecoverable, with the exception of the motor watchdog and hall sensor errors. Motor watchdog and hall sensor errors attempt to recover a set number of times before entering a nonrecoverable state.

diyarajon · 2024-01-13T21:40:48Z

Docs/source/Apps/ErrorHandling.rst

+* :doc:`ReadTritium <ReadTritium>`: Motor controller errors
+    * Errors sent from the motor controller are asserted by ReadTritium. These are typically nonrecoverable, with the exception of the motor watchdog and hall sensor errors.
+* :doc:`ReadCarCAN <ReadCarCAN>`: Contactor disable conditions
+    * These errors depend on BPS and include charge disable, contactor open, and BPS trip, as well as missed BPS messages.


Suggested change

* These errors depend on BPS and include charge disable, contactor open, and BPS trip, as well as missed BPS messages.

* These errors depend on BPS and include charge disable, contactor open, and BPS trip, as well as missed BPS messages. BPS trip is nonrecoverable, and all the other errors are recoverable. All the errors have callback functions.

* Added clang format/tidy config files, changes to the makefiles to apply them and edited the github workflow to make sure the tools are enforced * Applied clang format and tidy * Updated embedded shairpoint which has correct install script

…me like three hours)

…Hook

… Initialization (only in docs)

diyarajon

Looks good

Apps/Inc/ReadCarCAN.h

Apps/Inc/SendCarCan.h

Cam0Cow and others added 8 commits November 18, 2023 12:24

Update requirements.txt and overview

0ddd224

Fix up BSP layer docs

53a4c0e

Update conf and landing page

1dc6de1

Modify drivers docs

5d3ad04

Actually modified drivers docs

f28478b

Merge branch 'master' into docs-m2

09d6d40

fixed up docs for Main and ReadCarCAN

a1941e2

moved macros from ReadCarCAN.c to ReadCarCAN.h so they are visible in…

a778963

… docs

IshDeshpa added 4 commits December 19, 2023 17:38

fixed header comment so doxygen recognizes it

e28268a

created helper script for printing all sphinx references

c296b58

updated readtritium docs

d6e8247

updated Minions.rst

f9ce511

IshDeshpa requested review from babusid, diyarajon and KnockbackNemo December 19, 2023 23:50

IshDeshpa added 14 commits December 20, 2023 03:25

stash pop

f0bcf2a

small changes fixing sphinx warnings and other clerical issues

42e322c

changed all doxygengroups to doxygenfiles and removed all doxygengrou…

ca4b8c3

…ps entirely

ReadCarCAN complete

f9c44f7

documented SendTritium.h

101ec9e

added brief to SendTritium, fixed small build error in ReadCarCAN

15795a8

updated UpdateDisplay docs

ed5f51e

SendCarCAN updates

1ab2345

updated ReadTritium docs

aa132f9

almost finished with updating Apps layer docs

92be566

more updates to SendTritium docs

ddd5d49

build fix

9262e2f

changed ordering

9990303

NathanielDelgado requested changes Jan 10, 2024

View reviewed changes

Apps/Inc/SendTritium.h Outdated Show resolved Hide resolved

aidenmadaffri reviewed Jan 10, 2024

View reviewed changes

Apps/Inc/ReadTritium.h Outdated Show resolved Hide resolved

aidenmadaffri previously approved these changes Jan 10, 2024

View reviewed changes

KnockbackNemo requested changes Jan 11, 2024

View reviewed changes

IshDeshpa added 2 commits January 12, 2024 00:47

fixed ReadTritium

986a83c

more readtritium fixes

1f46742

diyarajon requested changes Jan 13, 2024

View reviewed changes

IshDeshpa and others added 7 commits January 13, 2024 16:20

Fixed ReadCarCAN

3c43fd4

updated SendTritium

540110a

updated UpdateDisplay docs

d9b9cb0

updates to naming

1778607

Dev/code cleanup again (#404)

d0bc272

* Added clang format/tidy config files, changes to the makefiles to apply them and edited the github workflow to make sure the tools are enforced * Applied clang format and tidy * Updated embedded shairpoint which has correct install script

update sendcarcan docs

1e96bb1

misc changes

affe4af

IshDeshpa dismissed aidenmadaffri’s stale review via affe4af January 20, 2024 19:21

NathanielDelgado and others added 8 commits January 20, 2024 15:27

Modifed workflow to enforce clang and format (#408)

972caef

Merge remote-tracking branch 'origin/master' into docs-m2 (This took …

efc5ab2

…me like three hours)

Merge branch 'master' into docs-m2

a059090

make format fixes

d44219e

applied clang tidy/format fixes and fixed build after merge

d04b2d4

renames

a4f2b0c

updated more naming, updated Tasks.c and added diagram for the TaskSw…

443c517

…Hook

got error handling to show up as a sub item of tasks, renamed Main to…

301d29a

… Initialization (only in docs)

diyarajon requested changes Jan 23, 2024

View reviewed changes

IshDeshpa added 2 commits January 23, 2024 22:48

minor edits

aeb852f

sendcarcan

ce338e0

IshDeshpa force-pushed the master branch from 1b2611a to cb913d5 Compare January 17, 2025 23:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs M2 #373

Docs M2 #373

Cam0Cow commented Dec 2, 2023 •

edited by IshDeshpa

Loading

IshDeshpa commented Dec 19, 2023

NathanielDelgado left a comment

aidenmadaffri commented Jan 10, 2024 •

edited

Loading

NathanielDelgado commented Jan 10, 2024

aidenmadaffri commented Jan 10, 2024

aidenmadaffri left a comment

KnockbackNemo left a comment

KnockbackNemo Jan 11, 2024

KnockbackNemo Jan 11, 2024

KnockbackNemo Jan 11, 2024

KnockbackNemo Jan 11, 2024

KnockbackNemo Jan 11, 2024

diyarajon left a comment

diyarajon Jan 11, 2024

diyarajon Jan 13, 2024

diyarajon Jan 13, 2024

diyarajon Jan 13, 2024

diyarajon Jan 13, 2024

diyarajon Jan 13, 2024

diyarajon Jan 13, 2024

diyarajon left a comment

	* @param pinmask Mask from stm header file that says which pin to write too
	* @param pinmask Mask from stm header file that says which pin to write to

	* @brief Transmits data to through a specific
	* @brief Transmits data through a specific

	* @param bus The bus to use, either be CARCAN or MOTORCAN
	* @param bus The bus to use, can either be CARCAN or MOTORCAN

	* @return ERROR if nothing was received so ignore id and data that was received. SUCCESS indicates data was received and stored.
	* @return ERROR if nothing was received, ignore id and data that was received. SUCCESS indicates data was received and stored.

	#. The Array Bypass-Precharge Contactor and Motor Bypass-Precharge Contactor will open
	#. The Array Precharge-Bypass Contactor and Motor Precharge-Bypass Contactor will open

	* Errors sent from the motor controller are asserted by ReadTritium. These are typically nonrecoverable, with the exception of the motor watchdog and hall sensor errors.
	* Errors sent from the motor controller are asserted by ReadTritium. These are typically nonrecoverable, with the exception of the motor watchdog and hall sensor errors. Motor watchdog and hall sensor errors attempt to recover a set number of times before entering a nonrecoverable state.

	* These errors depend on BPS and include charge disable, contactor open, and BPS trip, as well as missed BPS messages.
	* These errors depend on BPS and include charge disable, contactor open, and BPS trip, as well as missed BPS messages. BPS trip is nonrecoverable, and all the other errors are recoverable. All the errors have callback functions.

Docs M2 #373

Are you sure you want to change the base?

Docs M2 #373

Conversation

Cam0Cow commented Dec 2, 2023 • edited by IshDeshpa Loading

Quality Assurance Checklist

Requirements

Things to Consider

IshDeshpa commented Dec 19, 2023

NathanielDelgado left a comment

Choose a reason for hiding this comment

aidenmadaffri commented Jan 10, 2024 • edited Loading

NathanielDelgado commented Jan 10, 2024

aidenmadaffri commented Jan 10, 2024

aidenmadaffri left a comment

Choose a reason for hiding this comment

KnockbackNemo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

diyarajon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

diyarajon left a comment

Choose a reason for hiding this comment

Cam0Cow commented Dec 2, 2023 •

edited by IshDeshpa

Loading

aidenmadaffri commented Jan 10, 2024 •

edited

Loading