update documentation

- added 'Update-Languages.md'
- enhanced other doc files

Author: lukepistrol

Sources/CodeEditLanguages/Documentation.docc/Add-Languages.md

@@ -6,11 +6,13 @@ This article is a writedown on how to add support for more languages to ``CodeLa
 
 First of all have a look at the corresponding [GitHub Issue](https://github.com/CodeEditApp/CodeEditTextView/issues/15) to see which languages still need implementation.
 
+> Note: If you want to update existing languages see <doc:Update-Languages> instead.
+
 ## Add SPM support
 
 If you find one you want to add, fork and clone the linked repo and create a new branch `feature/spm`.
 
-> In the following code samples replace `{LANG}` or `{lang}` with the language you add (e.g.: `Swift` or `CPP` and `swift` or `cpp` respectively)
+> Tip: In the following code samples replace `{LANG}` or `{lang}` with the language you add (e.g.: `Swift` or `CPP` and `swift` or `cpp` respectively)
 
 ### .gitignore
 
@@ -20,7 +22,7 @@ Edit the `.gitignore` file to exclude the `.build/` directory from git.
 
 Create a new file `Package.swift` in the `root` directory of the repository and add the following configuration.
 
-> Make sure to remove the comment in 'sources'.
+> Warning: Make sure to remove the comment in 'sources'.
 
 ```swift
 // swift-tools-version:5.3
@@ -97,6 +99,8 @@ extern TSLanguage *tree_sitter_{lang}();
 
 In order to add a language to ``CodeEditLanguages`` you need to open the `.xcodeproj` file located inside `CodeLanguage-Container`.
 
+![.xcodeproj location](xcodeproj-location)
+
 1. Add the `tree-sitter` package you created earlier as a dependency like you would in a regular Xcode project.
 
 2. Then make sure the framework target loads the package module.
@@ -107,11 +111,19 @@ In order to add a language to ``CodeEditLanguages`` you need to open the `.xcode
     extern TSLanguage *tree_sitter_{lang}();
     ```
 
-    > Please keep an alphabetical order
+    > Important: Please keep an alphabetical order
 
 4. Now create the `xcframework` by running the `build_framework.sh` script from the Package's root directory.
+   ```bash
+   $ ./build_framework.sh
+   ```
 
 5. Check the output of the script. It should say `Done!` at the end.
+   ![build_framework.sh console output](build-output)
+   > Tip: If this does not succeed, try running the script using the `--debug` flag to get verbose output:
+   > ```bash
+   > $ ./build_framework.sh --debug
+   > ```
 
 6. You are now done in the Xcode Project and may close it now. Open the Package and continue.
 
@@ -148,10 +160,14 @@ private var tsLanguage: UnsafeMutablePointer<TSLanguage>? {
 On the bottom of the file add a new `static` constant:
 
 ```swift
-static let {lang}: CodeLanguage = .init(id: .{lang}, tsName: {lang}, extensions: [...])
+static let {lang}: CodeLanguage = .init(
+    id: .{lang}, 
+    tsName: {lang}, 
+    extensions: [...]
+)
 ```
 
-> in 'extensions' add the proper file extensions your language uses.
+> Important: in 'extensions' add the proper file extensions your language uses.
 
 Now find the static constant ``CodeLanguage/allLanguages`` and add your language to it:
 
@@ -192,7 +208,7 @@ Make sure to test the newly created language in a sample project!
 
 When everything is working correctly push your `tree-sitter-{lang}` changes to `origin` and also create a Pull Request to the official repository.
 
-> Take [this PR description](https://github.com/tree-sitter/tree-sitter-javascript/pull/223) as a template and cross-reference it with your Pull Request.
+> Tip: Take [this PR description](https://github.com/tree-sitter/tree-sitter-javascript/pull/223) as a template and cross-reference it with your Pull Request.
 
 Now you can remove the local dependencies and replace it with the actual package URLs and submit a Pull Request for `CodeEditTextView`.
 
@@ -224,6 +240,12 @@ Also make sure to add test cases for your new language in `Tests/CodeEditLanguag
     }
 ```
 
+### Run Tests locally
+
+Once you added your unit test cases run all tests locally on your machine by going to `Product>Test` or pressing `⌘+U` to make sure everything is working as intended.
+![unit test results](tests-results)
+
 ## Documentation
 
-Please make sure to add the newly created properties to the documentation `*.md` files.
+Please make sure to add the newly created properties to the documentation `*.md` files in the `Documentation.docc` catalog.
+![docs location](docs-location)

Sources/CodeEditLanguages/Documentation.docc/CodeLanguage.md

@@ -15,7 +15,7 @@ let fileURL = URL(fileURLWithPath: "/path/to/file.swift")
 let language = CodeLanguage.detectLanguageFrom(url: fileURL)
 ```
 
-> In case the language is not supported yet, the resulting ``CodeLanguage`` will be ``default`` (plain text).
+> Important: In case the language is not supported yet, the resulting ``CodeLanguage`` will be ``default`` (plain text).
 
 ### Supported Languages
 

Sources/CodeEditLanguages/Documentation.docc/Documentation.md

@@ -4,6 +4,8 @@ A collection of `tree-sitter` languages for syntax highlighting.
 
 ## Overview
 
+![logo](codeeditlanguages-logo)
+
 This package includes a binary framework `CodeLanguagesContainer.xcframework` which bundles all languages as a binary.
 
 The languages are then served as a ``CodeLanguage``.
@@ -13,6 +15,7 @@ The languages are then served as a ``CodeLanguage``.
 ### Guides
 
 - <doc:Add-Languages>
+- <doc:Update-Languages>
 
 ### Structs
 

Sources/CodeEditLanguages/Documentation.docc/Resources/build-output.png

@@ -4,7 +4,7 @@
 
 Since fetching queries *can* be expensive the queries are fetched lazily and kept in memory for the entire session.
 
-> Be aware that running the application in `Debug` configuration will lead to worse performance. Make sure to run it in `Release` configuration.
+> Warning: Be aware that running the application in `Debug` configuration will lead to worse performance. Make sure to run it in `Release` configuration.
 
 ## Usage
 

Sources/CodeEditLanguages/Documentation.docc/Resources/codeeditlanguages-logo.png

@@ -0,0 +1,48 @@
+# Update-Languages
+
+This article covers all the steps needed to update to the latest version of the `tree-sitter` languages
+
+## Overview
+
+From time to time the `tree-sitter` languages need to be updated to their latest version. This is pretty straight forward and can be done in less than 5 minutes.
+
+## Update the Dependencies
+
+1. Open the `CodeLanguages-Container.xcodeproj` which is located inside the `./CodeLanguages-Container` directory.
+   ![xcodeproj location](xcodeproj-location)
+
+2. Go to `File > Packages > Update to Latest Package Versions` and let it resolve the SPM dependencies.
+   > Note: Depending on your internet connection and Mac hardware this step can take a couple of minutes.
+
+3. Close the project
+
+> Tip: At this stage you can check if anything changed at all by checking the git status. If `Package.resolved` does not appear in the changed files list, you don't need to proceed.
+> ```bash
+> $ git status
+> ```
+
+## Update the Framework
+
+1. Open your terminal and set your working directory
+   ```bash
+   $ cd path/to/CodeEditLanguages
+   ```
+
+2. Run the `build_framework.sh` script
+   ```bash
+   $ ./build_framework.sh
+   ```
+   > Note: This script automatically removes old artifacts and replaces them with the new ones.
+
+3. Check the console output. It should say `Done!` at the end.
+   ![build output](build-output)
+   > Tip: If you don't get the output and the script terminates early, there might be an issue. Try running the script again with the `--debug` flag appended:
+   > ```bash
+   > $ ./build_framework.sh --debug
+   > ```
+
+## Check if everything still works
+
+1. Open the ``CodeEditLanguages`` Package in Xcode and run the included unit tests.
+
+2. Once all the tests succeeded, the changes can be committed, pushed and a pull request can be opened.