fix(docs): Update README and other docs to match the new build setup …

…and commit style
RichieSams · Oct 29, 2023 · 8450a88 · 8450a88
1 parent c59d7e3
commit 8450a88
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 59 deletions.
diff --git a/CONTRIBUTING.asciidoc b/CONTRIBUTING.asciidoc
@@ -10,18 +10,17 @@ The project has a code style. See the https://github.com/RichieSams/FiberTasking
 
 ## Git Commit Formatting
 
-Commits follow the following general style shown below. Chris Beams wrote an http://chris.beams.io/posts/git-commit/[excellent blog post] detailing this style. I highly suggest reading it.
+Commit messages must follow the https://www.conventionalcommits.org/en/v1.0.0/#summary[conventional commits] format. This allows us to automatically generate semantic-versioning and changelogs. In addition, the commit message information should roughly follow the style below. Chris Beams wrote an http://chris.beams.io/posts/git-commit/[excellent blog post] detailing this style. I highly suggest reading it.
 
 [source,txt]
 ----
-Summarize changes in around 50 characters or less
+<type>[optional scope]: Summarize changes in around 50 characters or less
 
-More detailed explanatory text, if necessary. Wrap it to about 72
-characters or so. In some contexts, the first line is treated as the
-subject of the commit and the rest of the text as the body. The
-blank line separating the summary from the body is critical (unless
-you omit the body entirely); various tools like `log`, `shortlog`
-and `rebase` can get confused if you run the two together.
+More detailed explanatory text, if necessary. In some contexts, 
+the first line is treated as the subject of the commit and the rest of
+the text as the body. The blank line separating the summary from the body
+is critical (unless you omit the body entirely); various tools like `log`,
+`shortlog` and `rebase` can get confused if you run the two together.
 
 Explain the problem that this commit is solving. Focus on why you
 are making this change as opposed to how (the code explains that).
@@ -30,9 +29,9 @@ change? Here's the place to explain them.
 
 Further paragraphs come after blank lines.
 
- - Bullet points are okay, too
+ * Bullet points are okay, too
 
- - Typically a hyphen or asterisk is used for the bullet, preceded
+ * Typically a hyphen or asterisk is used for the bullet, preceded
    by a single space, with blank lines in between, but conventions
    vary here
 
@@ -41,6 +40,8 @@ like this:
 
 Resolves: #123
 See also: #456, #789
+
+[optional footer]
 ----
 
 ## Code of Conduct

diff --git a/README.asciidoc b/README.asciidoc
@@ -5,7 +5,7 @@ This is a library for enabling task-based multi-threading. It allows execution o
 
 Under the covers, the task graph is executed using fibers, which in turn, are run on a pool of worker threads (one thread per CPU core). This allows the scheduler to wait on dependencies without task chaining or context switches. 
 
-This library was created as a proof of concept of the ideas presented by
+This library was first created as a proof of concept of the ideas presented by
 Christian Gyrling in his 2015 GDC Talk 'Parallelizing the Naughty Dog Engine Using Fibers'
 
 http://gdcvault.com/play/1022186/Parallelizing-the-Naughty-Dog-Engine[Free GDC Vault Recorded Presentation] +
@@ -88,7 +88,7 @@ int main() {
 			subset->end = triangleNum;
 		}
 
-		tasks[i] = {AddNumberSubset, subset};
+		tasks[i] = { AddNumberSubset, subset };
 
 		nextNumber = subset->end + 1;
 	}
@@ -111,6 +111,7 @@ int main() {
 
 	// Test
 	assert(triangleNum * (triangleNum + 1ULL) / 2ULL == result);
+	(void)result;
 
 	// Cleanup
 	delete[] subsets;
@@ -124,21 +125,8 @@ int main() {
 
 {blank}
 
-## Automatic Test Matrix
-
-
-|====
-2+^.^| Windows                                                                                                                                                                                                                                                                                           2+^.^| Linux                                                                                                                                                                                                                                                                              2+^.^| OSX
-<.^| Visual Studio 2019 <.^| image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=windows_vs_2019[Windows VC++ 2019 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"] <.^| GCC 9    | image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=linux_gcc_9[Linux GCC 9 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"]       <.^| GCC 9     <.^| image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=osx_gcc_9[OSX GCC 9 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"]
-<.^| Visual Studio 2022 <.^| image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=windows_vs_2022[Windows VC++ 2022 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"] <.^| GCC 12   | image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=linux_gcc_12[Linux GCC 12 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"]     <.^| GCC 12    <.^| image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=osx_gcc_12[OSX GCC 12 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"]
-<.^|                    <.^|                                                                                                                                                                                                                                                                               <.^| Clang 12 | image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=linux_clang_12[Linux Clang 12 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"] <.^| Clang 12  <.^| image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=osx_clang_12[OSX Clang 12 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"]
-<.^|                    <.^|                                                                                                                                                                                                                                                                               <.^| Clang 15 | image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=linux_clang_15[Linux Clang 15 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"] <.^| Clang 15  <.^| image:https://dev.azure.com/adastley/adastley/_apis/build/status/RichieSams.FiberTaskingLib?api-version=6.0-preview.1&label=build&branchName=master&job=osx_clang_15[OSX Clang 15 build status, link="https://dev.azure.com/adastley/adastley/_build?definitionId=1"]
-|====
-
-{blank}
-
 ## How it works
-Honestly, the best explanation is to watch Christian Gyrling's talk. It's free to watch (as of the time of writing) from the GDC vault. His explaination of fibers as well as how they used the fiber system in their game engine is excellent. However, I will try to give a TL;DR; version here.
+For a great introduction to fiber and the general idea, I would suggest watching Christian Gyrling's http://gdcvault.com/play/1022186/Parallelizing-the-Naughty-Dog-Engine[talk]. It's free to watch (as of the time of writing) from the GDC vault. That said, I will give an overview of how this library works below:
 
 ### What are fibers
 A https://msdn.microsoft.com/en-us/library/windows/desktop/ms682661%28v=vs.85%29.aspx[fiber] consists of a stack and a small storage space for registers. It's a very lightweight execution context that runs inside a thread. You can think of it as a shell of an actual thread. 
@@ -255,13 +243,11 @@ It's implemented behind the scenes with a TaskCounter, so if a Fibtex is locked,
 ## Supported Platforms
 
 |====
-| Arch   | Windows       | Linux         | OS X          | iOS       | Android
-| arm    | Needs testing | Tested OK     |               | In theory | In theory
-| arm_64 | Needs testing | Tested OK     |               | In theory | In theory
-| x86    | Tested OK     | Needs testing | Needs testing |           | In theory
-| x86_64 | Tested OK     | Tested OK     | Tested OK     |           | In theory
-| ppc    |               |               | In theory     |           | 
-| ppc_64 |               |               | In theory     |           | 
+| Arch   | Windows         | Linux           | OS X            | iOS       | Android
+| arm    | Needs testing   | Fully supported | In theory       | In theory | In theory
+| arm_64 | Needs testing   | Fully supported | Needs testing   | In theory | In theory
+| x86    | Fully supported | Needs testing   | Needs testing   |           | 
+| x86_64 | Fully supported | Fully supported | Fully supported |           | 
 |====
 
 {blank}

diff --git a/documentation/build_guide.asciidoc b/documentation/build_guide.asciidoc
@@ -66,14 +66,14 @@ $ cmake ../
 +
 [source,sh]
 ----
-$ make
+$ make -j
 ----
 +
 . Run the tests
 +
 [source,sh]
 ----
-$ make test
+$ ./tests/ftl-test
 ----
 
 {blank}

diff --git a/documentation/code_style.asciidoc b/documentation/code_style.asciidoc
@@ -4,7 +4,7 @@
 
 When writing code for FiberTaskingLib, I always try to follow these conventions. Sticking to a common set of formatting / indention rules makes it easier to read through the source base. Therefore, if you want to submit patches, please try to adhere to these rules.
 
-That said, I don't always follow these rules slavishly; in certain cases it is OK (and in fact might be favorable) to stray from them. Applying common sense, as usual, is a good idea. 
+I highly recommend just using clang-format to auto-format all your changes. Then you can skip most of the details of this page. I personally have clang-format set to run on save in my IDE. But there is also a Makefile command `format` that will run clang format on the entire code-base using docker.
 
 In the following examples, tabs are replaced by spaces for visual consistency on the web. But in actual code, use tabs for indentations. See below for more details.
 
@@ -451,7 +451,7 @@ Classes, structs, functions are documented using the javadoc style
 [source,cc]
 ----
 /**
- * Adds a group of tasks to the internal queue
+ * @brief Adds a group of tasks to the internal queue
  *
  * @param numTasks    The number of tasks
  * @param tasks       The tasks to queue
@@ -473,25 +473,3 @@ The following goes slightly beyond code formatting: We use certain keywords (tog
 
  * **FIXME:** marks code that contains hacks or bad/temporary workarounds, things that really should be revised at a later point.
  * **TODO:** marks incomplete code, or things that could be done better but are left for the future.
-
-
-== AStyle Program
-
-http://astyle.sourceforge.net/[ArtisticStyle] is a program that will format code according to a set of rules. While it doesn't support all of the conventions mentioned above, it will get it pretty close. Below are the command line arguments that I use.
-
-[source,sh]
-----
---style=java 
---indent=tab=4 
---align-pointer=name 
---align-reference=name 
---indent-preproc-block 
---indent-preproc-define 
---indent-preproc-cond 
---pad-oper 
---pad-header 
---unpad-paren 
---add-one-line-brackets 
---convert-tabs 
---mode=c
-----