Cleanup twig template documentation

Fantastic work!

Commit access granted! :-) Thanks a lot!

Great work @jwilson3

There has been some discussion about if we should output the variables as they would be output in the templates to make for more clarity and easier copy/paste http://drupal.org/node/1804710.

Should we use this:

//**
 * @file
 * Default theme implementation to display a node.
 *
 * Available variables:
 * - {{ label }}: the (sanitized) title of the node.
 * - {{ content }}: An array of node items. Use {{ content }} to print them all,

as opposed to this:

/**
 * @file
 * Default theme implementation to display a node.
 *
 * Available variables:
 * - label: the (sanitized) title of the node.
 * - content: An array of node items. Use {{ content }} to print them all,

It would be good to make the decision one way or the other. I prefer the use of the {{ item }} as it makes it easer to discern what the variables are, easier to copy paste and prevents ambiguity in the case where we might document twig tags eg. {% if page != true %}.

I made #1804710: [policy, no patch] Decide how to document Twig template files critical to discuss that there.

We are continuing in #1759168: Comments in twig files [policy, no patch], but it seems {{ }} is out. So docs should be fine.

Just a follow up here...

We talked about this in the weekly twig meeting today, and we decided that the existing syntax should be sufficient.

In PHPTemplate, we did NOT write this in the docs:

/**
 * @file
 * Default theme implementation to display a node.
 *
 * Available variables:
 * - <?php print $title ?>: the (sanitized) title of the node.
 ...

so there is no reason to include the print statements for Twig, either.

There will be plenty of examples how the variable is being printed, and evaluated, in the Twig code below, and we expect most front-end devs to copy and paste from there as well.

#9 looks good

jwilson: Thanks for fixing those themeable misspellings -- I personally don't care if it's considered a faux pas or not, it's appreciated. :)

I've been reversing the following change made in #1 in the core queue:

Removed parens after @see template_preprocess().

Per http://drupal.org/node/1354#see the parens need to be there for Doxygen formatting since they are functions.

I'm going to ask about getting sandbox access so I can fix these.

Thanks for all your work on this @jwilson3, I just made a couple commits here in the sandbox which should help during the transition to the core queue.