Structural changes to patterns subfolder (#219)

SUMMARY.md

@@ -10,10 +10,10 @@
   - [Finalisation in Destructors](./idioms/dtor-finally.md)
   - [`mem::{take(_), replace(_)}`](./idioms/mem-replace.md)
   - [On-Stack Dynamic Dispatch](./idioms/on-stack-dyn-dispatch.md)
-  - [Foreign function interface usage](./idioms/ffi-intro.md)
-    - [Idiomatic Errors](./idioms/ffi-errors.md)
-    - [Accepting Strings](./idioms/ffi-accepting-strings.md)
-    - [Passing Strings](./idioms/ffi-passing-strings.md)
+  - [Foreign function interface (FFI)](./idioms/ffi/intro.md)
+    - [Idiomatic Errors](./idioms/ffi/errors.md)
+    - [Accepting Strings](./idioms/ffi/accepting-strings.md)
+    - [Passing Strings](./idioms/ffi/passing-strings.md)
   - [Iterating over an `Option`](./idioms/option-iter.md)
   - [Pass Variables to Closure](./idioms/pass-var-to-closure.md)
   - [Privacy For Extensibility](./idioms/priv-extend.md)
@@ -21,20 +21,22 @@
   - [Temporary mutability](./idioms/temporary-mutability.md)
 
 - [Design Patterns](./patterns/index.md)
-  - [Builder](./patterns/builder.md)
-  - [Compose Structs](./patterns/compose-structs.md)
-  - [Entry API](./patterns/entry.md)
-  - [Foreign function interface usage](./patterns/ffi-intro.md)
-    - [Object-Based APIs](./patterns/ffi-export.md)
-    - [Type Consolidation into Wrappers](./patterns/ffi-wrappers.md)
-  - [Fold](./patterns/fold.md)
-  - [Interpreter](./patterns/interpreter.md)
-  - [Newtype](./patterns/newtype.md)
-  - [RAII Guards](./patterns/RAII.md)
-  - [Prefer Small Crates](./patterns/small-crates.md)
-  - [Strategy](./patterns/strategy.md)
-  - [Contain unsafety in small modules](./patterns/unsafe-mods.md)
-  - [Visitor](./patterns/visitor.md)
+  - [Behavioural](./patterns/behavioural/intro.md)
+    - [Interpreter](./patterns/behavioural/interpreter.md)
+    - [Newtype](./patterns/behavioural/newtype.md)
+    - [RAII Guards](./patterns/behavioural/RAII.md)
+    - [Strategy](./patterns/behavioural/strategy.md)
+    - [Visitor](./patterns/behavioural/visitor.md)
+  - [Creational](./patterns/creational/intro.md)
+    - [Builder](./patterns/creational/builder.md)
+    - [Fold](./patterns/creational/fold.md)
+  - [Structural](./patterns/structural/intro.md)
+    - [Compose Structs](./patterns/structural/compose-structs.md)
+    - [Prefer Small Crates](./patterns/structural/small-crates.md)
+    - [Contain unsafety in small modules](./patterns/structural/unsafe-mods.md)
+  - [Foreign function interface (FFI)](./patterns/ffi/intro.md)
+    - [Object-Based APIs](./patterns/ffi/export.md)
+    - [Type Consolidation into Wrappers](./patterns/ffi/wrappers.md)
 
 - [Anti-patterns](./anti_patterns/index.md)
   - [`#[deny(warnings)]`](./anti_patterns/deny-warnings.md)

idioms/ffi/intro.md

@@ -6,9 +6,9 @@ traps for inexperienced users of `unsafe` Rust.
 
 This section contains idioms that may be useful when doing FFI.
 
-1. [Idiomatic Errors](./ffi-errors.md) - Error handling with integer codes and
+1. [Idiomatic Errors](./errors.md) - Error handling with integer codes and
   sentinel return values (such as `NULL` pointers)
 
-2. [Accepting Strings](./ffi-accepting-strings.md) with minimal unsafe code
+2. [Accepting Strings](./accepting-strings.md) with minimal unsafe code
 
-3. [Passing Strings](./ffi-passing-strings.md) to FFI functions
+3. [Passing Strings](./passing-strings.md) to FFI functions

patterns/behavioural/intro.md

@@ -0,0 +1,6 @@
+# Behavioural Patterns
+
+From [Wikipedia](https://en.wikipedia.org/wiki/Behavioral_pattern):
+
+> Design patterns that identify common communication patterns among objects.
+> By doing so, these patterns increase flexibility in carrying out communication.

patterns/creational/intro.md

@@ -0,0 +1,8 @@
+# Creational Patterns
+
+From [Wikipedia](https://en.wikipedia.org/wiki/Creational_pattern):
+
+> Design patterns that deal with object creation mechanisms, trying to create objects
+> in a manner suitable to the situation. The basic form of object creation could
+> result in design problems or in added complexity to the design. Creational design
+> patterns solve this problem by somehow controlling this object creation.

patterns/entry.md

@@ -1,35 +0,0 @@
-# Entry API
-
-## Description
-
-A short, prose description of the pattern.
-
-## Example
-
-```rust
-// An example of the pattern in action, should be mostly code, commented
-// liberally.
-```
-
-## Motivation
-
-Why and where you should use the pattern
-
-## Advantages
-
-Good things about this pattern.
-
-## Disadvantages
-
-Bad things about this pattern. Possible contraindications.
-
-## Discussion
-
-TODO vs insert_or_update etc.
-
-## See also
-
-[RFC](https://github.com/rust-lang/rfcs/blob/master/text/0216-collection-views.md)
-[RFC](https://github.com/rust-lang/rfcs/blob/8e2d3a3341da533f846f61f10335b72c9a9f4740/text/0921-entry_v3.md)
-
-[Hashmap::entry docs](https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.entry)

patterns/ffi/export.md

@@ -246,15 +246,15 @@ Second, depending on the relationships of the API's parts, significant design ef
 may be involved. Many of the easier design points have other patterns associated
 with them:
 
-- [Wrapper Type Consolidation](./ffi-wrappers.md) groups multiple Rust types together
+- [Wrapper Type Consolidation](./wrappers.md) groups multiple Rust types together
   into an opaque "object"
 
-- [FFI Error Passing](../idioms/ffi-errors.md) explains error handling with integer
+- [FFI Error Passing](../idioms/ffi/errors.md) explains error handling with integer
   codes and sentinel return values (such as `NULL` pointers)
 
-- [Accepting Foreign Strings](../idioms/ffi-accepting-strings.md) allows accepting
+- [Accepting Foreign Strings](../idioms/ffi/accepting-strings.md) allows accepting
   strings with minimal unsafe code, and is easier to get right than
-  [Passing Strings to FFI](../idioms/ffi-passing-strings.md)
+  [Passing Strings to FFI](../idioms/ffi/passing-strings.md)
 
 However, not every API can be done this way.
 It is up to the best judgement of the programmer as to who their audience is.

patterns/ffi/intro.md

@@ -6,8 +6,8 @@ for inexperienced users of unsafe Rust.
 
 This section contains design patterns that may be useful when doing FFI.
 
-1. [Object-Based API](./ffi-export.md) design that has good memory safety characteristics,
+1. [Object-Based API](./export.md) design that has good memory safety characteristics,
   and a clean boundary of what is safe and what is unsafe
 
-2. [Type Consolidation into Wrappers](./ffi-wrappers.md) - group multiple Rust types
+2. [Type Consolidation into Wrappers](./wrappers.md) - group multiple Rust types
   together into an opaque "object"

patterns/ffi/wrappers.md

@@ -63,7 +63,7 @@ As a result, the wrapper is simple and contains no `unsafe` code.
 ## Advantages
 
 This makes APIs safer to use, avoiding issues with lifetimes between types.
-See [Object-Based APIs](./ffi-export.md) for more on the advantages and pitfalls
+See [Object-Based APIs](./export.md) for more on the advantages and pitfalls
 this avoids.
 
 ## Disadvantages

patterns/late-bounds.md

@@ -1,35 +0,0 @@
-# Late bound bounds
-
-## Description
-
-TODO late binding of bounds for better APIs (i.e., Mutex's don't require Send)
-
-## Example
-
-```rust
-// An example of the pattern in action, should be mostly code, commented
-// liberally.
-```
-
-## Motivation
-
-Why and where you should use the pattern
-
-## Advantages
-
-Good things about this pattern.
-
-## Disadvantages
-
-Bad things about this pattern. Possible contraindications.
-
-## Discussion
-
-A deeper discussion about this pattern. You might want to cover how this is done
-in other languages, alternative approaches, why this is particularly nice in
-Rust, etc.
-
-## See also
-
-Related patterns (link to the pattern file). Versions of this pattern in other
-languages.

patterns/structural/intro.md

@@ -0,0 +1,6 @@
+# Structural Patterns
+
+From [Wikipedia](https://en.wikipedia.org/wiki/Structural_pattern):
+
+> Design patterns that ease the design by identifying a simple way to realize relationships
+> among entities.