Merge pull request #1 from Z80coder/doc-test

Z80coder · web-flow · commit bdd6f3e1ce09 · 2020-04-27T16:50:26.000+01:00
Doc test
diff --git a/README.md b/README.md
@@ -1,6 +1,11 @@
 # datalog-cpp
+
 implementation of datalog (without negation, and semi-naive bottom-up evaluation) in C++
 
 work-in-progress
 
 not yet alpha!
+
+## Documentation
+
+- [Quick git how to](./docs/git-how-to.md)
diff --git a/docs/git-how-to.md b/docs/git-how-to.md
@@ -0,0 +1,92 @@
+# Quick git how to
+
+Quick instructions on how to contribute to this repo from the command line.
+
+Please see link to other resources below.
+
+## 1. Clone the repo on your local machine
+
+```
+git clone git@github.com:Z80coder/datalog-cpp.git
+```
+
+You should now have a `datalog-cpp` folder. 
+
+```
+cd datalog-cpp
+```
+
+## 2. Update the master branch
+
+
+```
+git checkout master
+git pull
+```
+
+## 3. Create a new branch for your work
+
+You will develop your code in your own branch. First you need to create it.
+
+```
+git checkout -b your_branch_name
+
+git push --set-upstream origin your_branch_name
+```
+
+## 4. Or switch to your existing branch for your work
+
+If you already done the step above, then ensure you are in your branch when you write code.
+
+```
+git checkout your_branch_name
+```
+
+## 5. Do some coding
+
+Work as normal
+
+## 6. Commit your changes
+
+Type
+```
+git status
+```
+to check which files you've added or changed. Note the files you want to commit at this time, then:
+```
+git add newfile1 newfile2
+```
+Then commit the changes
+```
+git commit
+```
+
+## 7. Push your changes to GitHub
+
+All you've done so far is declare some changes. You haven't yet pushed them to the GitHub repo. Let's do that now.
+
+```
+git push
+```
+
+You can keep adding, committing and pushing until you're ready to open a pull-request (with the intent of merging the changes in your branch into the `master` on the repo).
+
+## 8. Open a pull-request
+
+Go to https://github.com/Z80coder/datalog-cpp
+
+Click on the `Branch` button and look for `your_branch_name`, and then click on it.
+
+You should see a `New pull request` button. Click it and follow the user-interface prompts to create a pull-request.
+
+Once reviewed, your branch will be merged. You can contribute a new collection of changes by returning to `Create a new branch for your work` above.
+
+## Other resources
+
+- Microsoft Visual Studio has git support built in, and there's a GitHub plugin for Visual Studio to enable direct cloning from GitHub repos.
+
+- Microsoft Visual Code also has plug-in extensions that support Git
+
+- https://guides.github.com/ has some useful guides.
+
+- Also, there's a GitHub Desktop app: https://desktop.github.com/
diff --git a/src/Variable.h b/src/Variable.h
@@ -15,30 +15,47 @@ using namespace std;
 template <typename T>
 struct Variable : optional<T>
 {
+    /**
+     * @brief bind this variable to the supplied value (making it an unfree variable)
+     * 
+     * @param value
+     */
     void bind(const T &value)
     {
         this->emplace(value);
     }
 
+    /**
+     * @brief unbinds this variable (making it a free variable)
+     * 
+     */
     void unbind()
     {
         this->reset();
     }
 
+    /**
+     * @brief checks whether this variable is free or bound
+     * 
+     * @return true if bound to a value
+     * @return false if free
+     */
     bool isBound() const
     {
         return this->has_value();
     }
 
-    const T &
-    value() const
+    /**
+     * @brief returns the bound value (if not bound then throws an exception)
+     * 
+     * @return const T& 
+     */
+    const T &value() const
     {
         return this->optional<T>::value();
     }
 };
 
-// TODO: use auto more for return type of functions
-
 template <typename T>
 Variable<T> *var()
 {

Original file line number	Diff line number	Diff line change
`@@ -15,30 +15,47 @@ using namespace std;`
`15`	`15`	`template <typename T>`
`16`	`16`	`struct Variable : optional<T>`
`17`	`17`	`{`
	`18`	`+ /**`
	`19`	`+ * @brief bind this variable to the supplied value (making it an unfree variable)`
	`20`	`+ *`
	`21`	`+ * @param value`
	`22`	`+ */`
`18`	`23`	`void bind(const T &value)`
`19`	`24`	`{`
`20`	`25`	`this->emplace(value);`
`21`	`26`	`}`
`22`	`27`
	`28`	`+ /**`
	`29`	`+ * @brief unbinds this variable (making it a free variable)`
	`30`	`+ *`
	`31`	`+ */`
`23`	`32`	`void unbind()`
`24`	`33`	`{`
`25`	`34`	`this->reset();`
`26`	`35`	`}`
`27`	`36`
	`37`	`+ /**`
	`38`	`+ * @brief checks whether this variable is free or bound`
	`39`	`+ *`
	`40`	`+ * @return true if bound to a value`
	`41`	`+ * @return false if free`
	`42`	`+ */`
`28`	`43`	`bool isBound() const`
`29`	`44`	`{`
`30`	`45`	`return this->has_value();`
`31`	`46`	`}`
`32`	`47`
`33`		`- const T &`
`34`		`- value() const`
	`48`	`+ /**`
	`49`	`+ * @brief returns the bound value (if not bound then throws an exception)`
	`50`	`+ *`
	`51`	`+ * @return const T&`
	`52`	`+ */`
	`53`	`+ const T &value() const`
`35`	`54`	`{`
`36`	`55`	`return this->optional<T>::value();`
`37`	`56`	`}`
`38`	`57`	`};`
`39`	`58`
`40`		`-// TODO: use auto more for return type of functions`
`41`		`-`
`42`	`59`	`template <typename T>`
`43`	`60`	`Variable<T> *var()`
`44`	`61`	`{`