text: Title: Document what `factory.PostGeneration` and `factory.post_generation` should return
  Body: #### The problem
  
  In `reference.rst`, it's a bit unclear what `PostGeneration` and `post_generation` can and should return... What's more, reading the code it looks like one should be wary of shadowing declaration of `BaseDeclaration`. Would you mind documenting this? Thanks!
  