Updated documentation and appearance.

.gitattributes

@@ -1,2 +0,0 @@
-*.h linguist-language=C++
-*.tmpl linguist-language=HTML

README.md

@@ -1,39 +1,15 @@
 # Better Enums
 
-Reflective compile-time C++ enum library with clean syntax, in a single header
+Reflective compile-time enum library with clean syntax, in a single header
-file. For example:
+file.
 
-    #include <enum.h>
+![Better Enums code overview][sample]
-    ENUM(Channel, uint8_t, Red = 1, Green, Blue)
 
-defines a type `Channel`. You can then do natural things such as:
+[sample]: https://raw.githubusercontent.com/aantron/better-enums/0.10.1/doc/image/sample.gif
 
-```cpp
+[![Try online][wandbox-img]][wandbox] [![0.10.1][version]][releases]
-Channel channel = Channel::Green;
 
-channel._to_string();           // Results in the string "Green"
+In C++11, *everything* can be used at compile time. You can convert your enums,
-Channel::_from_string("Red");   // Results in Channel::Red
-
-Channel::_from_integral(3);     // Checked cast, Channel::Blue
-
-Channel::_size;                 // Number of channels (3)
-Channel::_values()[0];          // Get the first channel
-
-for (Channel channel : Channel::_values()) {
-    process(channel);           // Iterate over all channels
-}
-
-// Automatic case checking, just as with a built-in enum.
-switch (channel) {
-    case Channel::Red:   break;
-    case Channel::Green: break;
-    case Channel::Blue:  break;
-}
-```
-
-...and more. You can try it live [here][wandbox].
-
-In C++11, *everything* is available at compile time. You can convert your enums,
 loop over them, [find their max][max],
 [statically enforce conventions][enforce], and pass along the results as
 template arguments or to `constexpr` functions. All the reflection is available
@@ -48,13 +24,19 @@ See the [project page][project] for full documentation.
 [max]:      http://aantron.github.io/better-enums/demo/BitSets.html
 [enforce]:  http://aantron.github.io/better-enums/demo/SpecialValues.html
 [project]:  http://aantron.github.io/better-enums
-[wandbox]: http://melpon.org/wandbox/permlink/pdlAAGoxnjqG6FRI
+[wandbox]:  http://melpon.org/wandbox/permlink/pdlAAGoxnjqG6FRI
+[tutorial]: http://aantron.github.io/better-enums#Tutorial
+[api]:      http://aantron.github.io/better-enums/ApiReference.html
+[releases]: https://github.com/aantron/better-enums/releases
+
+[wandbox-img]: https://img.shields.io/badge/try%20it-online-blue.svg
+[version]:     https://img.shields.io/badge/version-0.10.1-lightgrey.svg
 
 ## Installation
 
 Simply add `enum.h` to your project &mdash; that's it.
 
-Then, include it and use the `ENUM` macro. Your compiler will generate the rich
+Then, include it, and use the `ENUM` macro. Your compiler will generate the rich
 enums that are missing from standard C++.
 
 ## Additional features
@@ -66,10 +48,10 @@ enums that are missing from standard C++.
   compiler as much as [just including `iostream` does][performance].
 - Use any initializers and sparse ranges, just like with a built-in enum.
 - Guaranteed size and alignment &mdash; you choose the representation type.
-- Stream operators supported.
+- Stream operators.
 - Does not use the heap and can be compiled with exceptions disabled, for use in
   minimal freestanding environments.
-- The underlying type [can be an object type][underlying].
+- The underlying type [does not have to be an integral type][underlying].
 
 [performance]: http://aantron.github.io/better-enums/Performance.html
 [underlying]: http://aantron.github.io/better-enums/demo/NonIntegralUnderlyingTypes.html
@@ -78,7 +60,7 @@ enums that are missing from standard C++.
 
 The biggest limitation is that the `ENUM` macro can't be used inside a class.
 This seems [difficult to remove][nested]. There is a workaround with `typedef`
-(or `using`):
+(or C++11 `using`):
 
 ```cpp
 ENUM(UniquePrefix_Color, uint8_t, Red, Green, Blue)
@@ -95,20 +77,34 @@ You can, however, use `ENUM` inside a namespace.
 
 [nested]: http://aantron.github.io/better-enums/DesignDecisionsFAQ.html#NoEnumInsideClass
 
-## Contact
+## Contact and development
 
 Don't hesitate to contact me about features or bugs:
 [antonbachin@yahoo.com][email], Twitter [@better_enums][twitter], or open an
 issue on GitHub.
 
-[email]:   mailto:antonbachin@yahoo.com
+If you'd like to help develop Better Enums, see [CONTRIBUTING][contributing].
-[twitter]: https://twitter.com/better_enums
+
+[![master kept stable][stable]][commits] [![Travis status][travis-img]][travis]
+[![AppVeyor status][appveyor-img]][appveyor]
+
+[email]:        mailto:antonbachin@yahoo.com
+[twitter]:      https://twitter.com/better_enums
+[contributing]: https://github.com/aantron/better-enums/blob/master/doc/CONTRIBUTING.md
+[stable]:       https://img.shields.io/badge/master-kept_stable-brightgreen.svg
+[commits]:      https://github.com/aantron/better-enums/blob/master/doc/CONTRIBUTING.md#commits
+
+[appveyor]:     https://ci.appveyor.com/project/aantron/better-enums/branch/master
+[travis]:       https://travis-ci.org/aantron/better-enums/branches
+[travis-img]:   https://img.shields.io/travis/aantron/better-enums/master.svg?label=travis
+[appveyor-img]: https://img.shields.io/appveyor/ci/aantron/better-enums/master.svg?label=appveyor
 
 ## License and history
 
-Better Enums is released under the BSD 2-clause license. See
+Better Enums is released under the BSD 2-clause license. See [LICENSE][license].
-[LICENSE](https://github.com/aantron/better-enums/blob/master/LICENSE).
 
 The library was originally developed by the author in the winter of 2012-2013 at
 Hudson River Trading, as a replacement for an older generator called
 `BETTER_ENUM`.
+
+[license]: https://github.com/aantron/better-enums/blob/master/doc/LICENSE

doc/CONTRIBUTING.md

@@ -25,6 +25,10 @@ locally, you can run either the `unix` or `ms` target in `test/Makefile` to test
 on a specific compiler. Open the `Makefile` file and find the targets for
 instructions.
 
+If your pull request does not include any changes to the code (for example, you
+have changed only documentation), add the text `[ci skip]` to the commit message
+to prevent AppVeyor and Travis from testing the commit.
+
 The `make` targets mentioned above depend on the following software:
 
 - Make
@@ -59,6 +63,11 @@ to edit commit messages when merging into `master`. I will also squash multiple
 commits in most cases. If you prefer I not do either one, let me know, but then
 we will have to go back and forth on the exact contents of the pull request.
 
+I am maintaining the `master` branch in such a way that every commit passes its
+tests, i.e. `master` is always stable. Every commit going into `master` is first
+fully tested in its pull request branch, or in a temporary staging branch, if
+necessary.
+
 ## Generating the documentation
 
 To generate an offline copy of the documentation, run `make -C doc`. To view it,

doc/DesignDecisionsFAQ.md

@@ -196,6 +196,9 @@ However, it also introduces some difficulties.
 - Scoped constants are lost for $cxx98 unless Better Enums again wraps them in a
   generated type, though it will be more lightweight than a full Better Enum of
   the non-traits approach.
+- Traits types must be specialized in either the same namespace scope they are
+  declared in, or in an enclosing scope. This makes it impossible to declare an
+  enum and specialize traits for it in a user's custom namespace.
 - Traits types are not intuitive for some $cxx users, which would present a
   barrier to usage.
 
@@ -239,6 +242,32 @@ data structures — something I haven't gotten to yet because there doesn't
 seem to be a data structure to measure that is not disqualified by the speed of
 generation.
 
+### Why not use indices for the representation?
+
+Representing Better Enum values by their indices in the declaration list seems
+like a tempting solution for the problem of having multiple constants with the
+same numeric value. It also speeds up some operations. For example, if a Better
+Enum is simply an index, then getting its string representation is simply
+indexing an array, rather than some kind of data structure lookup.
+
+    // Representations 0, 1, 2, 3 instead of 1, 2, 3, 1.
+    <em>ENUM(Kind, int, A = 1, B, C, D = A)</em>
+
+Choosing this approach has serious drawbacks.
+
+- The data structure lookup has simply been moved to another place. It now takes
+  time to convert from a literal `Kind::D` to a Better Enum.
+- It is still impossible to disambiguate between the literals `Kind::D` and
+  `Kind::A` (1 and 1). Only the Better Enums objects of type `Kind` that
+  represent `D` and `A` are different from each other (0 and 3). This is not
+  only a technical problem, but is also quite unintuitive.
+- Treating a Better Enum represented by an index as untyped memory produces
+  surprising results. This makes Better Enums much less useful with functions
+  such as `fwrite`. Worse, Better Enums become sensitive to declaration order
+  even when initializers are given explicitly. Using indices for the
+  representation makes it difficult to maintain compatibility with external
+  protocols and file formats.
+
 [contact]: ${prefix}Contact.html
 [traits]: #Traits
 [implicit]: ${prefix}OptInFeatures.html#StrictConversions

doc/Makefile

@@ -8,9 +8,9 @@ html :
 
 .PHONY : publish
 publish : prepare
-	cp -r html ../doc-publish
+	cp -r html/* ../doc-publish
-	git commit --amend
+	cd ../doc-publish && git add . && git commit --amend --reset-author && \
-	git push -f
+		git push -f
 
 .PHONY : prepare
 prepare : examples web

doc/better-enums.css

@@ -577,3 +577,7 @@ h3.contents {
 .buttons-bar iframe.gh-watch {
     width: 103px;
 }
+
+.external {
+    font-size: 75%;
+}

doc/docs.py

@@ -140,7 +140,9 @@ def compose_general_page(relative_path):
     write_page(relative_path, text)
 
 def list_general_pages():
-    return glob.glob("*.md")
+    return filter(
+        lambda s: not os.path.splitext(os.path.basename(s))[0].isupper(),
+        glob.glob("*.md"))
 
 def process_threaded(directory):
     sources = glob.glob(os.path.join(directory, "*.md"))

doc/index.md

@@ -202,6 +202,11 @@ Try it live online in
       <li>
         <a href="${prefix}DesignDecisionsFAQ.html">Design decisions FAQ</a>
       </li>
+      <li>
+        <a href="http://www.codeproject.com/Articles/1002895/Clean-Reflective-Enums-Enum-to-String-with-Nice-Sy">
+          Implementation <span class="external">[CodeProject]</span>
+        </a>
+      </li>
     </ul>
   </li>
 

doc/template/footer.tmpl

@@ -4,7 +4,8 @@
 <footer>
   <div class="container">
     Copyright &copy; 2015 Anton Bachin. Released under the BSD 2-clause license.
-    See <a href="https://github.com/aantron/better-enums/blob/master/LICENSE">
+    See
+    <a href="https://github.com/aantron/better-enums/blob/$ref/doc/LICENSE">
     LICENSE</a>.
     <br />
     This page is part of the documentation for Better Enums $version.

doc/template/ref.tmpl

@@ -1 +1 @@
-0.10.0
+0.10.1

doc/template/version.tmpl

@@ -1 +1 @@
-0.10.0
+0.10.1

enum.h

@@ -1,5 +1,5 @@
 // This file is part of Better Enums, released under the BSD 2-clause license.
-// See LICENSE for details, or visit http://github.com/aantron/better-enums.
+// See doc/LICENSE for details, or visit http://github.com/aantron/better-enums.
 
 #pragma once
 

test/Makefile

@@ -1,7 +1,7 @@
 # Run "make" for quick builds while developing.
 # Run "make default-all" before submitting a pull request.
 # Run "make clean" to clean up.
-# See CONTRIBUTING.md for full instructions.
+# See doc/CONTRIBUTING.md for full instructions.
 
 CXXTEST_GENERATED := cxxtest/tests.cc