Merge pull request faif#211 from lucasloisp/short-descriptions

Add short descriptions to Abstract Factory, Builder and ObjectPool

creational/abstract_factory.py

@@ -1,9 +1,34 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
+"""
+*What is this pattern about?
+The Abstract Factory Pattern serves to provide an interface for
+creating related/dependent objects without need to specify their
+actual class.
+The idea is to abstract the creation of objects depending on business
+logic, platform choice, etc.
+
+*What does this example do?
+This particular implementation abstracts the creation of a pet and
+does so depending on the AnimalFactory we chose (Dog or Cat)
+This works because both Dog/Cat and their factories respect a common
+interface (.speak(), get_pet() and get_food()).
+Now my application can create pets (and feed them) abstractly and decide later,
+based on my own criteria, dogs over cats.
+The second example allows us to create pets based on the string passed by the
+user, using cls.__subclasses__ (the list of sub classes for class cls)
+and  sub_cls.__name__ to get its name.
+
+*Where is the pattern used practically?
+
+*References:
+https://sourcemaking.com/design_patterns/abstract_factory
+http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
+
+"""
+
 
-"""Implementation of the abstract factory pattern"""
 import six
 import abc
 import random

creational/builder.py

@@ -2,8 +2,28 @@
 # -*- coding : utf-8 -*-
 
 """
+*What is this pattern about?
+It decouples the creation of a complex object and its representation,
+so that the same process can be reused to build objects from the same
+family.
+This is useful when you must separate the specification of an object
+from its actual representation (generally for abstraction).
+
+*What does this example do?
+This particular example uses a Director to abtract the
+construction of a building. The user specifies a Builder (House or
+Flat) and the director specifies the methods in the order necessary
+creating a different building dependding on the sepcified
+specification (through the Builder class).
+
 @author: Diogenes Augusto Fernandes Herminio <[email protected]>
 https://gist.github.com/420905#file_builder_python.py
+
+*Where is the pattern used practically?
+
+*References:
+https://sourcemaking.com/design_patterns/builder
+
 """
 
 

creational/pool.py

@@ -2,11 +2,33 @@
 # -*- coding: utf-8 -*-
 
 """
+*What is this pattern about?
+This pattern is used when creating an object is costly (and they are
+created frequently) but only a few are used at a time. With a Pool we
+can manage those instances we have as of now by caching them. Now it
+is possible to skip the costly creation of an object if one is
+available in the pool.
+A pool allows to 'check out' an inactive object and then to return it.
+If none are available the pool creates one to provide without wait.
+
+*What does this example do?
+In this example queue.Queue is used to create the pool (wrapped in a
+custom ObjectPool object to use with the with statement), and it is
+populated with strings.
+As we can see, the first string object put in "yam" is USED by the
+with statement. But because it is released back into the pool
+aftwerwards it is reused by the explicit call to sample_queue.get().
+Same thing happens with "sam", when the ObjectPool created insided the
+function is deleted (by the GC) and the object is returned.
+
+*Where is the pattern used practically?
+
+*References:
 http://stackoverflow.com/questions/1514120/python-implementation-of-the-object-pool-design-pattern
+https://sourcemaking.com/design_patterns/object_pool
 """
 
 
-
 class ObjectPool(object):
 
     def __init__(self, queue, auto_get=False):