Included PR comments

docs/en/manuals/extensions_best_practices.md

@@ -1,22 +1,18 @@
 # Best Practices
 
-Writing cross platform code can be difficult, but there are some ways to make it easier to both develop and maintain.
-Here we list some ways we at Defold work with cross platform native code and API's.
+Writing cross platform code can be difficult, but there are some ways to make it easier to both develop and maintain. In this document we list some ways we at Defold work with cross platform native code and API's.
 
 ## Defold code
 
-In the Defold engine we use C++ very sparingly. In fact, most code is very C-like.
-We avoid templates, except for a few container classes, due to the fact that templates both incurs a cost on compilation times
-as well as executable size.
+In the Defold engine we use C++ very sparingly. In fact, most code is very C-like. We avoid templates, except for a few container classes, due to the fact that templates both incurs a cost on compilation times as well as executable size.
 
 ### C++ version
 
-The defold source it built with the default C++ version of each compiler (See [Native Extensions - Best Practices](/manuals/extensions_best_practices#_)).
+The Defold source is built with the default C++ version of each compiler (See [Native Extensions - Best Practices](/manuals/extensions_best_practices#_)).
 
-We avoid using the latest features or versions of C++. Mostly because we already have what we need to build an game engine.
-Keeping track of the latest features of C++ is a time consuming task, and to really master those features will require a lot of precious time.
+We avoid using the latest features or versions of C++. Mostly because we already have what we need to build a game engine. Keeping track of the latest features of C++ is a time consuming task, and to really master those features will require a lot of precious time.
 
-It also has the added benefit for our extension developers that we keep a stable ABI.
+It also has the added benefit for our extension developers that we keep a stable ABI. Also worth pointing out is that using the latest C++ features may prevent the code from compiling on different platforms due to varying support.
 
 ### Standard Template Libraries - STL
 
@@ -24,7 +20,7 @@ Since the Defold engine doesn't use any STL code, except for some algorithms and
 
 Again, bear in mind that ABI incompatibilites may hinder you when using your extension in conjunction with other extensions or 3rd party libraries.
 
-Avoiding the (heavily tepmlated) STL libraries, also improves on our build times, and more importantly, the executable size.
+Avoiding the (heavily templated) STL libraries, also improves on our build times, and more importantly, the executable size.
 
 #### Strings
 
@@ -35,26 +31,23 @@ For us, it's better to use `const char*` and a few helper functions.
 
 ### Make functions hidden
 
-Use the `static` keywork on functions local to your compile unit if possible. This lets the compiler do some optimizations, and
-can both improve performance as well as reduce executable size.
+Use the `static` keywork on functions local to your compile unit if possible. This lets the compiler do some optimizations, and can both improve performance as well as reduce executable size.
 
 # 3rd party libraries
 
 When choosing a 3rd party library to use (regardless of language), we consider at least these things:
 
 * Functionality - Does it solve the particular problem you have?
-* Performance - Does it infer a performance cost in the runtime? For each frame, or
-* Library size - How much bigger will the final executable be? Is it acceptable
-* Dependencies - Does it require extra libraries
-* Support - What state is the library in? Does it have many open issues? Is it still maintained? etc...
+* Performance - Does it infer a performance cost in the runtime?
+* Library size - How much bigger will the final executable be? Is it acceptable?
+* Dependencies - Does it require extra libraries?
+* Support - What state is the library in? Does it have many open issues? Is it still maintained?
 * License - Is it ok to use for this project?
 
 
 # Open source dependencies
 
-Always make sure that you have access to your dependencies.
-E.g. if you depend on something on github, there's nothing preventing that repository either being removed, or suddenly changes
-direction or ownership.
+Always make sure that you have access to your dependencies. E.g. if you depend on something on GitHub, there's nothing preventing that repository either being removed, or suddenly changes direction or ownership. You can mitigate this risk by forking the repository and using your fork instead of the upstream project.
 
 The code in that library will be injected into your game, so make sure the library does what it's supposed to do, and nothing more!
 
@@ -67,8 +60,7 @@ When creating an extension, there are a few things that help out in developing i
 
 ## Lua api
 
-There should only be one Lua api, and one implementation of it.
-This makes it a lot easier to behave the same for all platforms.
+There should only be one Lua api, and one implementation of it. This makes it a lot easier to behave the same for all platforms.
 
 If the platform in question shouldn't support the extension, we recommend simply not registering a Lua module at all.
 That way you can detect support by checking for nil:
@@ -127,5 +119,3 @@ So for instance, put platform specific libraries under:
                             /libFoo.a
         /arm64-android
                             /libFoo.a
-
-

docs/en/manuals/extensions_build_variants.md

@@ -14,58 +14,43 @@ Note: When you choose `Build and run` you'll get the debug version.
 
 ### Debug
 
-This type of executable still has the debugging feature left inside it, such as:
-profiling, logging and hot reload.
-
-This variant is chosen during development of the game.
+This type of executable still has the debugging feature left inside it, such as profiling, logging and hot reload. This variant is chosen during development of the game.
 
 ### Release
 
-This variant has the debugging features disabled.
-This options is chosen when the game is ready to be released to the app store.
+This variant has the debugging features disabled. This options is chosen when the game is ready to be released to the app store.
 
 ### Headless
 
-This executable runs without any graphics. It means that you can run the game unit/smoke tests on a CI server,
-or even have it as a game server in the cloud.
+This executable runs without any graphics and sound. It means that you can run the game unit/smoke tests on a CI server, or even have it as a game server in the cloud.
 
 ## App Manifest
 
-Not only can you add native code to the engine with the Native Extensions feature, you can also remove standard parts of the engine.
-E.g. if you don't need a physics engine, you can remove that from the executable.
+Not only can you add native code to the engine with the Native Extensions feature, you can also remove standard parts of the engine. E.g. if you don't need a physics engine, you can remove that from the executable.
 
-We support this via a file called an `App Manifest` (.appmanifest).
-In such a file, you can configure what libraries or symbols to remove, or perhaps add compile flags
+We support this via a file called an `App Manifest` (.appmanifest). In such a file, you can configure what libraries or symbols to remove, or perhaps add compile flags
 
-This feature is still in the works, and needs more attention.
+This feature is still being developed and improved.
 
 ### Combined context
 
-The app manifest actually has the same structure and syntax as the extension manifest.
-This allows us to merge the contexts for one platform together when finally building.
+The app manifest actually has the same structure and syntax as the extension manifest. This allows us to merge the contexts for one platform together when finally building.
 
-And, Defold itself, has its own build manifest as the foundation (`build.yml`).
-For each extension that is built, the manifests are combined as follows:
+And, Defold itself, has its own build manifest as the foundation (`build.yml`). For each extension that is built, the manifests are combined as follows:
 
 	manifest = merge(game.appmanifest, ext.manifest, build.yml)
 
-This is so the user can override the default behaviour of the engine and also each extension.
-
-And, for the final link stage, we merge the app manifest with the defold manifest:
+This is so the user can override the default behaviour of the engine and also each extension. And, for the final link stage, we merge the app manifest with the defold manifest:
 
 	manifest = merge(game.appmanifest, build.yml)
 
 ### Editing
 
-Currently, the process can be done manually, but we recommend our users to use the [Manifestation](https://britzl.github.io/manifestation/) tool
-to create their app manifest.
-
-Eventually, the creation and modification of the app manifests will be done in the Editor.
+Currently, the process can be done manually, but we recommend our users to use the [Manifestation](https://britzl.github.io/manifestation/) tool to create their app manifest. Eventually, the creation and modification of the app manifests will be done in the Editor.
 
 ### Syntax
 
-Here is an exampple from the [Manifestation](https://britzl.github.io/manifestation/) tool for reference.
-(Subject to change. Don't copy this file directly. Instead, use the online tool)
+Here is an example from the [Manifestation](https://britzl.github.io/manifestation/) tool for reference (Subject to change. Don't copy this file directly. Instead, use the online tool):
 
 	platforms:
 	    x86_64-osx:
@@ -129,8 +114,7 @@ Here is an exampple from the [Manifestation](https://britzl.github.io/manifestat
 
 #### White listing
 
-For all the keywords, we apply white listing filter.
-This is to avoid illegal path handling and accessing files outside of the build upload folder.
+For all the keywords, we apply white listing filter. This is to avoid illegal path handling and accessing files outside of the build upload folder.
 
 #### linkFlags
 
@@ -138,10 +122,7 @@ Here you can add flags to the specific platform compiler.
 
 #### libs
 
-This flag is only used if you wish to add a library that is part of the platform or Defold SDK.
-All libraries in your app's extensions are added automatically, and you shouldn't add those to this flag.
-
-Here's an example where the 3D physics is removed from the engine:
+This flag is only used if you wish to add a library that is part of the platform or Defold SDK. All libraries in your app's extensions are added automatically, and you shouldn't add those to this flag. Here's an example where the 3D physics is removed from the engine:
 
     x86_64-linux:
         context:
@@ -152,10 +133,7 @@ Here's an example where the 3D physics is removed from the engine:
 
 #### Exclude flags
 
-These flags are used to remove things previously defined in the platform context.
-
-Here's an example of how to remove the Facebook extensiokn from the engine.
-Note the `(.*)` which is a regexp to help remove the correct items.
+These flags are used to remove things previously defined in the platform context. Here's an example of how to remove the Facebook extension from the engine (Note the `(.*)` which is a regexp to help remove the correct items).
 
     armv7-android:
         context:
@@ -167,7 +145,6 @@ Note the `(.*)` which is a regexp to help remove the correct items.
 
 #### Where's the list of all flags, libraries, symbols???
 
-We might put some of them here, but we also think our time is better spent
-completing the feature of moving the manifest configuration into the Editor, making it a seamless step for the user.
+We might put some of them here, but we also think our time is better spent completing the feature of moving the manifest configuration into the Editor, making it a seamless step for the user.
 
 In the meantime, we'll keep the [Manifestation](https://britzl.github.io/manifestation/) tool updated.