Update comments.

Author: csyonghe

docs/build_reference.ps1

@@ -1,16 +1,34 @@
+# This script uses `slangc` to generate stdlib reference documentation and push the updated
+# documents to shader-slang/stdlib-reference repository.
+# The stdlib-reference repository has github-pages setup so that the markdown files we generate
+# in this step will be rendered as html pages by Jekyll upon a commit to the repository.
+# So we we need to do here is to pull the stdlib-reference repository, regenerate the markdown files
+# and push the changes back to the repository.
+
+# The generated markdown files will be located in three folders:
+# - ./global-decls
+# - ./interfaces
+# - ./types
+# In addition, slangc will generate a table of content file `toc.html` which will be copied to
+# ./_includes/stdlib-reference-toc.html for Jekyll for consume it correctly.
+
 # If stdlib-reference folder does not exist, clone from github repo
 if (-not (Test-Path ".\stdlib-reference")) {
     git clone https://github.com/shader-slang/stdlib-reference/
 }
 else {
+# If it already exist, just pull the latest changes.
     cd stdlib-reference
     git pull
     cd ../
 }
+# Remove the old generated files.
 Remove-Item -Path ".\stdlib-reference\global-decls" -Recurse -Force
 Remove-Item -Path ".\stdlib-reference\interfaces" -Recurse -Force
 Remove-Item -Path ".\stdlib-reference\types" -Recurse -Force
 
+# Use git describe to produce a version string and write it to _includes/version.inc.
+# This file will be included by the stdlib-reference Jekyll template.
 git describe --tags | Out-File -FilePath ".\stdlib-reference\_includes\version.inc" -Encoding ASCII
 
 cd stdlib-reference