From 55af5ec3b44be836d9178a6c45c9b3ff27eb5e58 Mon Sep 17 00:00:00 2001 From: Christian glacet Date: Fri, 31 Oct 2025 16:10:16 +0100 Subject: [PATCH 1/4] Format Flower class methods indentation to limit line wrap With the default font size, on the website this code was a bit messy. --- concepts/headers/introduction.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/concepts/headers/introduction.md b/concepts/headers/introduction.md index e7db48e1..c33c0951 100644 --- a/concepts/headers/introduction.md +++ b/concepts/headers/introduction.md @@ -72,10 +72,18 @@ namespace robots { ```cpp // A file named robot_flower.cpp #include "robot_flower.h" -robots::Flower::Flower(std::string name, int size) {this->name = "Robotica " + name; this->size = size;} -void robots::Flower::start_next_day() {if (!needs_water) ++size; needs_water = true;} -std::string robots::Flower::get_name() {return name;} -int robots::Flower::get_size() {return size;} +robots::Flower::Flower(std::string name, int size) { + this->name = "Robotica " + name; this->size = size; +} +void robots::Flower::start_next_day() { + if (!needs_water) ++size; needs_water = true; +} +std::string robots::Flower::get_name() { + return name; +} +int robots::Flower::get_size() { + return size; +} ``` When the header is used as an API overview, that is where a person would look for information like default values. From 3c4878cc14e63fc78bbf1530f7aabf92debf9727 Mon Sep 17 00:00:00 2001 From: Christian glacet Date: Fri, 31 Oct 2025 16:15:06 +0100 Subject: [PATCH 2/4] remove same line multiple instruction in robot_flower.cpp example --- concepts/headers/introduction.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/concepts/headers/introduction.md b/concepts/headers/introduction.md index c33c0951..b4a24440 100644 --- a/concepts/headers/introduction.md +++ b/concepts/headers/introduction.md @@ -73,10 +73,12 @@ namespace robots { // A file named robot_flower.cpp #include "robot_flower.h" robots::Flower::Flower(std::string name, int size) { - this->name = "Robotica " + name; this->size = size; + this->name = "Robotica " + name; + this->size = size; } void robots::Flower::start_next_day() { - if (!needs_water) ++size; needs_water = true; + if (!needs_water) ++size; + needs_water = true; } std::string robots::Flower::get_name() { return name; From 5c7ffa972f58a565a26e518ad1ce55212f20bd2c Mon Sep 17 00:00:00 2001 From: Alexander Hans Date: Sun, 2 Nov 2025 12:35:01 +0100 Subject: [PATCH 3/4] use clang-format-doc and add newlines --- concepts/headers/about.md | 115 ++++++++++++++++++++----------- concepts/headers/introduction.md | 100 +++++++++++++++++---------- 2 files changed, 137 insertions(+), 78 deletions(-) diff --git a/concepts/headers/about.md b/concepts/headers/about.md index 8d59dcba..b5d91008 100644 --- a/concepts/headers/about.md +++ b/concepts/headers/about.md @@ -18,17 +18,24 @@ If you want to write a library called "quick_math" that offers a function "super ```cpp // A file named quick_math.h #pragma once + namespace quick_math { - double super_root(double x, int n); + +double super_root(double x, int n); + } ``` ```cpp // A file named quick_math.cpp -#include "quick_math.h" #include + +#include "quick_math.h" + double quick_math::super_root(double x, int n) { - while(n) { x = std::sqrt(x), --n;} + while (n) { + x = std::sqrt(x), --n; + } return x; } ``` @@ -51,31 +58,45 @@ One possible layout is to keep all the implementation details in the source file // A file named robot_flower.h #if !defined(ROBOT_FLOWER_H) #define ROBOT_FLOWER_H + #include + namespace robots { - class Flower { - private: - bool needs_water{}; - int size{}; - std::string name{}; - public: - Flower(std::string name, int size = 0); - void give_water(); - std::string get_name(); - int get_size(); - void start_next_day(); - }; -} + +class Flower { + private: + bool needs_water{}; + int size{}; + std::string name{}; + + public: + Flower(std::string name, int size = 0); + void give_water(); + std::string get_name(); + int get_size(); + void start_next_day(); +}; +} // namespace robots #endif ``` ```cpp // A file named robot_flower.cpp #include "robot_flower.h" -robots::Flower::Flower(std::string name, int size) {this->name = "Robotica " + name; this->size = size;} -void robots::Flower::start_next_day() {if (!needs_water) ++size; needs_water = true;} -std::string robots::Flower::get_name() {return name;} -int robots::Flower::get_size() {return size;} + +robots::Flower::Flower(std::string name, int size) { + this->name = "Robotica " + name; + this->size = size; +} + +void robots::Flower::start_next_day() { + if (!needs_water) ++size; + needs_water = true; +} + +std::string robots::Flower::get_name() { return name; } + +int robots::Flower::get_size() { return size; } ``` When the header is used as an API overview, that is where a person would look for information like default values. @@ -87,21 +108,35 @@ Another layout option is a _header only_ library, that does not have a `.cpp` fi ```cpp // A file named robot_flower.h #pragma once + #include + namespace robots { - class Flower { - private: - bool needs_water{}; - int size{}; - std::string name{}; - public: - Flower(std::string name, int size = 0) {this->name = "Robotica " + name; this->size = size;} - void give_water() {needs_water = false;} - std::string get_name() {return name;} - int get_size() {return size;} - void start_next_day() {if (!needs_water) ++size; needs_water = true;} - }; -} + +class Flower { + private: + bool needs_water{}; + int size{}; + std::string name{}; + + public: + Flower(std::string name, int size = 0) { + this->name = "Robotica " + name; + this->size = size; + } + + void give_water() { needs_water = false; } + + std::string get_name() { return name; } + + int get_size() { return size; } + + void start_next_day() { + if (!needs_water) ++size; + needs_water = true; + } +}; +} // namespace robots ``` Projects might use combinations of these layouts and there is a lot of discussion as to what might be the best fit for each use case. @@ -129,9 +164,7 @@ int myFunction(int n) { } } -int myOtherFunction(int m) { - return myFunction(m / 2); -} +int myOtherFunction(int m) { return myFunction(m / 2); } ``` When `myFunction` is defined, the compiler does not know about `myOtherFunction` yet. @@ -142,8 +175,8 @@ The compiler assumes that the definition will follow at some later point after t The next example shows how a forward declaration is used for functions. ```cpp -int myFunction(int n); // Forward declaration of myFunction -int myOtherFunction(int m); // Forward declaration of myOtherFunction +int myFunction(int n); // Forward declaration of myFunction +int myOtherFunction(int m); // Forward declaration of myOtherFunction // Definition of myFunction int myFunction(int n) { @@ -155,9 +188,7 @@ int myFunction(int n) { } // Definition of myOtherFunction -int myOtherFunction(int m) { - return myFunction(m / 2); -} +int myOtherFunction(int m) { return myFunction(m / 2); } ``` ## Include Guards via ifndef @@ -178,7 +209,9 @@ The syntax can be seen below with `MY_HEADER_FILE_H` as a variable. ```cpp #ifndef MY_HEADER_FILE_H /* any name uniquely mapped to file name */ #define MY_HEADER_FILE_H + // file content + #endif ``` diff --git a/concepts/headers/introduction.md b/concepts/headers/introduction.md index b4a24440..c7b258b6 100644 --- a/concepts/headers/introduction.md +++ b/concepts/headers/introduction.md @@ -18,17 +18,24 @@ If you want to write a library called "quick_math" that offers a function "super ```cpp // A file named quick_math.h #pragma once + namespace quick_math { - double super_root(double x, int n); -} + +double super_root(double x, int n); + +} // namespace quick_math ``` ```cpp // A file named quick_math.cpp -#include "quick_math.h" #include + +#include "quick_math.h" + double quick_math::super_root(double x, int n) { - while(n) { x = std::sqrt(x), --n;} + while (n) { + x = std::sqrt(x), --n; + } return x; } ``` @@ -51,41 +58,49 @@ One possible layout is to keep all the implementation details in the source file // A file named robot_flower.h #if !defined(ROBOT_FLOWER_H) #define ROBOT_FLOWER_H + #include + namespace robots { - class Flower { - private: - bool needs_water{}; - int size{}; - std::string name{}; - public: - Flower(std::string name, int size = 0); - void give_water(); - std::string get_name(); - int get_size(); - void start_next_day(); - }; -} + +class Flower { + private: + bool needs_water{}; + int size{}; + std::string name{}; + + public: + Flower(std::string name, int size = 0); + void give_water(); + std::string get_name(); + int get_size(); + void start_next_day(); +}; + +} // namespace robots + #endif ``` ```cpp // A file named robot_flower.cpp #include "robot_flower.h" + robots::Flower::Flower(std::string name, int size) { this->name = "Robotica " + name; this->size = size; } + void robots::Flower::start_next_day() { - if (!needs_water) ++size; + if (!needs_water) { + ++size; + } needs_water = true; } -std::string robots::Flower::get_name() { - return name; -} -int robots::Flower::get_size() { - return size; -} + +std::string robots::Flower::get_name() { return name; } + +int robots::Flower::get_size() { return size; } ``` When the header is used as an API overview, that is where a person would look for information like default values. @@ -97,21 +112,32 @@ Another layout option is a _header only_ library, that does not have a `.cpp` fi ```cpp // A file named robot_flower.h #pragma once + #include + namespace robots { - class Flower { - private: - bool needs_water{}; - int size{}; - std::string name{}; - public: - Flower(std::string name, int size = 0) {this->name = "Robotica " + name; this->size = size;} - void give_water() {needs_water = false;} - std::string get_name() {return name;} - int get_size() {return size;} - void start_next_day() {if (!needs_water) ++size; needs_water = true;} - }; -} + +class Flower { + private: + bool needs_water{}; + int size{}; + std::string name{}; + + public: + Flower(std::string name, int size = 0) { + this->name = "Robotica " + name; + this->size = size; + } + void give_water() { needs_water = false; } + std::string get_name() { return name; } + int get_size() { return size; } + void start_next_day() { + if (!needs_water) ++size; + needs_water = true; + } +}; + +} // namespace robots ``` Projects might use combinations of these layouts and there is a lot of discussion as to what might be the best fit for each use case. From 39d70b0debe1a1ca77522b0508ff048dd6b445c0 Mon Sep 17 00:00:00 2001 From: Alexander Hans Date: Sun, 2 Nov 2025 12:40:07 +0100 Subject: [PATCH 4/4] make consistent --- concepts/headers/about.md | 4 ---- concepts/headers/introduction.md | 4 +++- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/concepts/headers/about.md b/concepts/headers/about.md index b5d91008..5983cd3c 100644 --- a/concepts/headers/about.md +++ b/concepts/headers/about.md @@ -124,13 +124,9 @@ class Flower { this->name = "Robotica " + name; this->size = size; } - void give_water() { needs_water = false; } - std::string get_name() { return name; } - int get_size() { return size; } - void start_next_day() { if (!needs_water) ++size; needs_water = true; diff --git a/concepts/headers/introduction.md b/concepts/headers/introduction.md index c7b258b6..978b94c6 100644 --- a/concepts/headers/introduction.md +++ b/concepts/headers/introduction.md @@ -132,7 +132,9 @@ class Flower { std::string get_name() { return name; } int get_size() { return size; } void start_next_day() { - if (!needs_water) ++size; + if (!needs_water) { + ++size; + } needs_water = true; } };