Migrate CLion page (needs update still) and doc tips page

multiplemonomials · multiplemonomials · commit 11987a13d26b · 2025-07-12T11:46:56.000-07:00
diff --git a/.gitignore b/.gitignore
@@ -4,4 +4,7 @@ site/
 
 # Python venv
 .venv/
-venv/
+venv/
+
+# Mac stuff
+.DS_Store
diff --git a/docs/.nav.yml b/docs/.nav.yml
@@ -9,4 +9,4 @@ nav:
   - contributing.md
   - maintainers.md
   - mbed-history-and-mbed-ce.md
-  - For Developers: for-developers
+  - For Mbed CE Developers: for-developers
diff --git a/docs/for-developers/doxygen-tips.md b/docs/for-developers/doxygen-tips.md
@@ -0,0 +1,223 @@
+# Doxygen Documentation Tips
+
+This page will collect some tips on how to write and structure documentation so that it fits into the Mbed CE docs.
+
+## Running Doxygen Locally
+If you have created or edited significant amounts of documentation, it's recommended to run Doxygen locally to check your docs.  After installing Doxygen (>=1.9.1), docs can be generated by opening a terminal in the `mbed-os` root folder and running:
+
+```
+$ doxygen ./doxyfile_options
+```
+
+Docs will be generated in the BUILD folder, and any errors will be printed to the screen.
+
+## File Header
+
+At minimum, each file should contain a block like this near the top:
+
+```cpp
+/**
+ * \file
+ *
+ * Copyright (c) 202X SOME-NAME
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * \brief <one-sentence description of what's in this file>
+ */
+```
+
+The [\file](https://www.doxygen.nl/manual/commands.html#cmdfile) command tells Doxygen to include stuff from this file in the output docs.  The \brief command sets the description of the file.
+
+## Groups
+In order to organize the documentation into manageable chunks, Doxygen groups have been used.  These group commands create a hierarchy in the output docs:
+
+![Doc Group Hierarchy](img/docs-hierarchy.png)
+
+The top-level group is mbed-os-public ("Public API"), which is defined in AnalogIn.h (for some reason).  All public code should be defined in this group or one of its subgroups.  For instance, if you wanted to add a new driver API alongside I2C and SPI, you'd add that into the `drivers-public-api` group, which would put it under "Public API" &gt; "Drivers" in the hierarchy.
+
+### Adding Code to an Existing Group
+To add entities (defines, functions, classes) in code to an existing group, they need to be surrounded by a structure like this:
+
+```cpp
+/**
+ * \ingroup drivers-public-api
+ * @{
+ */
+
+/**
+ * \brief Description of SomeFunction
+ */
+void SomeFunction();
+
+/**
+ * \brief Description of MyNewDriver
+ */
+class MyNewDriver
+{
+...
+};
+
+/// @}
+```
+
+Note: You must be careful that "@}" and "@{" are correctly matched within a file, or a doxygen error will be produced.  Additionally, note that Doxygen groups **cannot span namespace boundaries**.
+
+For example, the following is incorrect and will create a (hard to diagnose) error:
+
+```cpp
+/**
+ * \ingroup drivers-public-api-gpio
+ * @{
+ */
+
+namespace mbed {
+
+class SomeClass
+{
+...
+};
+
+/// @}
+
+}
+```
+
+Instead, the Doxygen commands must be inside the namespace boundaries:
+
+```cpp
+
+namespace mbed {
+
+/**
+ * \ingroup drivers-public-api-gpio
+ * @{
+ */
+
+class SomeClass
+{
+...
+};
+
+/// @}
+
+}
+```
+
+This is, similarly, not OK: 
+
+```cpp
+
+namespace mbed {
+
+/**
+ * \ingroup drivers-public-api-gpio
+ * @{
+ */
+
+void foo();
+
+namespace detail
+{
+void bar();
+}
+
+void baz();
+
+/// @}
+
+}
+```
+
+Tedious though it is, you must do: 
+
+```cpp
+
+namespace mbed {
+
+/**
+ * \ingroup drivers-public-api-gpio
+ * @{
+ */
+
+void foo();
+
+/// @}
+
+namespace detail
+{
+void bar();
+}
+
+/**
+ * \ingroup drivers-public-api-gpio
+ * @{
+ */
+
+void baz();
+
+/// @}
+
+}
+```
+
+Thankfully, if your file contains only a single class, you can completely skip the @{ and @} and just add the class to the group directly:
+```cpp
+/**
+ * \brief Description of MyNewDriver
+ * \ingroup drivers-public-api
+ */
+class MyNewDriver
+{
+...
+};
+```
+
+### Adding Code to a New Group
+If, instead, you want to create a new group for your new driver, you'd use the defgroup command:
+
+```cpp
+/**
+ * \defgroup my-driver-group My Driver Human-Readable Name
+ * \ingroup drivers-public-api
+ * @{
+ */
+
+class MyNewDriver
+{
+...
+};
+
+/// @}
+```
+
+This will create a new group in your code.  It can be referenced by \ingroup commands as `my-driver-group`, and will show as "My Driver Human-Readable Name" in the output docs.  
+
+Note: A group name should only be defined by a \defgroup command **in one place**. 
+
+## Rules for Extraction
+There are several rules that control whether a given entity (function, constant, class, etc) in code is or is not extracted into the documentation.  Missing something?  Check that all of the following conditions are satisfied:
+
+1. The code file containing the entity is not excluded by `EXCLUDE_PATTERNS` in doxyfile_options
+1. The code file containing the entity has a Doxygen comment somewhere with an `\file` command in it.
+2. The section of code containing the entity is not inside an `#ifdef` block, or, if it is, that the relevant define is included in the `PREDEFINED` block in doxyfile_options.  Currently this has to be updated manually :(
+3. The specific entity is documented.  Since doxygen is configured with `EXTRACT_ALL` as false, only entities with a `/**` or `///` comment will be included in the docs.
+
+Note: for documenting one-line things like macros and enum entries, the `///<` construct is helpful.  The following:
+
+```cpp
+#define MY_DEFINE_1 1 ///< Docs for define one
+#define MY_DEFINE_2 2 ///< Docs for define two
+```
+
+is equivalent to:
+
+```cpp
+/// Docs for define one
+#define MY_DEFINE_1 1 
+
+/// Docs for define two
+#define MY_DEFINE_2 2
+```
+
+## Documenting Overridden Functions
+If you've used Javadoc, you might be familiar with the "@inheritDoc" directive, which is used to copy the documentation from a superclass function to a function in a subclass that overrides it.  Doxygen, in contrast, does not have this directive.  Instead, if you override a superclass function, just don't add any docs to it at all.  This will cause Doxygen to copy the docs from the superclass. 
diff --git a/docs/for-developers/img/docs-hierarchy.png b/docs/for-developers/img/docs-hierarchy.png
diff --git a/docs/getting-started/ide_cli_setup/cli_setup.md b/docs/getting-started/ide_cli_setup/cli_setup.md
@@ -0,0 +1,20 @@
+# CLI Setup
+
+This page will show you how to take an existing Mbed CE project, build it, and debug it using command line tools.
+
+## Building
+1. Open a terminal in the project directory.
+2. Create and enter a build directory: `mkdir build && cd build`
+3. Run CMake: `cmake .. -GNinja -DCMAKE_BUILD_TYPE=Develop -DMBED_TARGET=<your mbed target>`
+    - Valid options for the MBED_TARGET option are any supported Mbed OS board target, such as `LPC1768` or `NUCLEO_F429ZI`
+    - The Develop build type is recommended for normal development work, but there is also the Debug build type which disables optimizations, and the Release build type which disables debug information.
+4. Build the project by running `ninja`
+5. If the project has an executable which can be flashed, and you have an upload method configured (see below), run `ninja flash-<executable>` to upload it to a connected device.
+
+## Debugging
+
+Suppose you want to debug an executable by the name of MyProgram.  
+
+1. First, if you haven't already, you will need to make sure the project is configured to use an upload method that supports debugging.  Read about upload methods on the [Upload Methods page](../../upload-methods.md), and select a method to use using the `-DUPLOAD_METHOD=<method>` flag to CMake. 
+2. Now, plug in your target and start a GDB server for it by running `ninja gdbserver` in the build directory.
+3. Finally, open another terminal in the build directory and run `ninja debug-MyProgram`.  You should be dropped into a GDB session connected to your target!
diff --git a/docs/getting-started/ide_cli_setup/clion_setup.md b/docs/getting-started/ide_cli_setup/clion_setup.md
@@ -0,0 +1,72 @@
+# CLion Setup
+
+This page will show you how to take an existing Mbed CE project and use it with the CLion IDE.
+
+## Installing CLion
+
+Note: CLion is a paid product for commercial use, costing about $100 yearly (there's a subscription, but if you cancel it you can keep using your current version forever).  However, it is free for students if you fill out the application [here](https://www.jetbrains.com/community/education/#students). There is also a free 30-day trial available for everyone. I (Jamie) can say that it's the best C++ IDE I've personally used, and I highly recommend giving it a shot.
+
+1. Download the CLion installer from the [download page](https://www.jetbrains.com/clion/download/).
+    a. You can also use the [JetBrains Toolbox](https://www.jetbrains.com/toolbox-app/) app to make installing and updating multiple JetBrains IDEs easier.
+2. On Windows/Mac, run the installer and go through the install.  You can then run CLion from your OS menu.  On Linux, you'll get a tar file instead.  Extract the tar file to Downloads, and move the folder to /opt/.  Then, you will be able to run CLion by executing `/opt/clion-20xx.x.x/bin/clion.sh` in a terminal.
+3. The first time you open CLion you will get a license screen.  You can use the "start trial" button to just use the 30 day trial, or if you have a license you should log in with your JetBrains account.
+4.  You should now be at the IDE start screen!
+
+![image](https://user-images.githubusercontent.com/2099358/187101127-f3cdba83-2932-4c56-8eba-8e96ec781c1b.png)
+
+## Importing the Project
+1. Now, in CLion, click on Open, then browse to the root folder of your project.  Then, click OK.
+
+![image](https://user-images.githubusercontent.com/2099358/187101223-2e95b918-11b6-4275-9dc8-d4e063f83f45.png)
+
+2. You'll likely get the below trust dialog box.  Click on Trust Project.
+
+![image](https://user-images.githubusercontent.com/2099358/187101279-83d64ed6-0e80-4671-93bf-ac8b935d6f67.png)
+
+3. If this is your first project, CLion will ask about setting up a toolchain.  You can accept the defaults here and click Next, because the Mbed build system overrides the compiler selection.
+
+![image](https://user-images.githubusercontent.com/2099358/187101341-b8bb3788-61be-4182-b44e-979d81f223a4.png)
+
+4. Now, you will get a wizard to create a build profile.  For now, change the "Name" and "Build type" settings to "Develop".  Also, in the "CMake Options" field, set MBED_TARGET to match your board name (e.g. `-DMBED_TARGET=NUCLEO_L452RE_P` for the Nucleo L452RE board). Also, optionally you can specify the [upload method](https://github.com/mbed-ce/mbed-os/wiki/Upload-Methods) to use.  Or, leave this unset to use the Mbed OS defaults for your board.
+    - If you need Debug or Release configurations, you can come back here later and create them following the same process.
+
+![Build Profiles Screen](https://user-images.githubusercontent.com/2099358/188508936-ed9958f1-ae2c-472d-b507-ef7bec556419.png)
+
+Finally, hit Finish.
+
+5.  If all goes well, you should see the CMake project successfully configure and load.  If not, you may need to double-check the [toolchain setup guide](https://github.com/mbed-ce/mbed-os/wiki/Toolchain-Setup-Guide) to make sure everything is set up OK.
+
+NOTE: When working with Mbed projects, the Tools > CMake > Reset Cache and Reload Project option is your friend if things break.  If your project did not find the compilers successfully, things moved on the disk, or you're getting other errors, make it your first recourse to try this option.
+
+![image](https://user-images.githubusercontent.com/2099358/187102104-81c52e9c-dbd8-435c-82fa-20eb68a25dc7.png)
+
+## Flashing Code
+
+To flash code, find the entry labeled `flash-<your target>` in the menu at the top right.  Then, click the hammer button (NOT the play button).
+
+![image](https://user-images.githubusercontent.com/2099358/187102170-dfa3beb1-9d19-4333-8d67-a5e92c3a07d0.png)
+
+Note: Mbed OS tends to clutter this menu up with its own targets.  To find your target quickly, you can just start typing with the menu open, and it will search the list.  Maybe this is obvious to you but it took me like 4 years to find this...
+
+![image](https://user-images.githubusercontent.com/2099358/187102307-85664d9f-78ee-4c06-8503-9cec7c4cc232.png)
+
+## Debugging
+1. First, if you haven't already, you will need to make sure the project is configured to use an upload method that supports debugging. Read about upload methods on the [Upload Methods page](https://github.com/mbed-ce/mbed-os/wiki/Upload-Methods), and select a method to use using the -DUPLOAD_METHOD=<method> flag to CMake.  Note: you can edit the CMake flags that you initially configured by going to Settings > Build, Execution, Deployment > CMake.
+2. Additionally, you will need to set the `MBED_CLION_PROFILE_NAME` CMake variable to match the exact name of the profile.  This is needed in order to generate debug configuration files correctly.
+![image](https://user-images.githubusercontent.com/2099358/220048699-4a22c44a-ccac-49db-9e2e-c9a003c2405b.png)
+3. In CLion, find the GDB debug configuration for your executable in the targets menu.  This will be near the bottom and start with "GDB", then your target name.  Make sure to select the one that matches your build type too -- if you are working in the Develop configuration, don't pick the Debug one!
+
+![image](https://user-images.githubusercontent.com/2099358/220049391-a89dc7b4-188a-48fd-96fa-446c8263ad68.png)
+
+4. With the configuration selected, click the green bug button at the top.  If source files have been modified, the code will be rebuilt and downloaded to the target.  Then, GDB will start.
+
+Note: If you wish to have the code stop at main(), you must set a breakpoint there before starting the debug session.
+
+Note: With CLion, the GDB command line console is available by going to the GDB tab in the Debug panel.  You can use this console in parallel with the GUI to evaluate expressions and set breakpoints.
+
+![image](https://user-images.githubusercontent.com/2099358/187105850-0632954a-6ecb-44ae-960d-d848ef732cc8.png)
+
+Note: To reset the MCU, press the R-with-a-bar-over-it button.
+
+### Tips
+- **Increasing GDB Timeout:** Sometimes, on Mbed, when you have deeply nested stack frames and lots of local variables, GDB can take a very long time to load after you hit a breakpoint, on the order of a minute.  This can cause CLion to time out and terminate the debugger session.  You can change the timeout by following [these instructions](https://www.jetbrains.com/help/clion/configuring-debugger-options.html#gdb-startup).  I'd recommend at least 120000 ms.
diff --git a/docs/getting-started/ide_cli_setup/vscode_setup.md b/docs/getting-started/ide_cli_setup/vscode_setup.md
@@ -123,7 +123,7 @@ You can watch this part in video version - [Youtube guide](https://youtu.be/9ZDH
 5. Click on the bottom bar where it says "No Kit Selected". Then, choose "[Unspecified]" from the menu (the Mbed build scripts will find the compilers).
    ![VS Code Unspecified Kit](img/vs-code-unspecified-kit.png)
    
-7. Now, select your variant. Use Ctrl-Shift-P and find CMake: Select Variant or use same on bottom bar. Then choose the variant you want.  I'd recommend starting with the Develop one for general use.
+7. Now, select your variant. Use Ctrl-Shift-P and find CMake: Select Variant or use same on bottom bar. Then choose the variant you want.  I'd recommend starting with the Develop one for general use.  
    ![VS Code Selecting a Variant](img/vs-code-select-variant.png)
    ![VS Code Variant Dialog](img/vs-code-variant-dialog.png)
 
