Comments in twig files [policy, no patch]

I'm not sure what the "Doxygen team" thinks - it will be important to hear from them - but I think we should leave the doc blocks at the top of the files very similar to the way they are now, like so:

{#
/**
 * @file
 * Default theme implementation to display a region.
 *
 * Available variables:
 * - content: The content for this region, typically blocks.
 * - attributes: Array of attributes
 * - attributes.class: String of classes that can be used to style contextually through CSS.
 *
 * @see template_preprocess()
 * @see template_preprocess_region()
 */
#}

My thought is that we'll certainly have to add some extra magic to make the parsing on the API site work, and my thoughts were that if we left it this way then all we'd need to do is strip off an additional twig comment indicator at the beginning and at the end of the docblock.

(I didn't see a patch here, so changing status)

As the maintainer of the API project (which generates api.drupal.org), I am in favor of #1. I will be able to make a simple patch to the API module parser to parse a file that looks like this and display the documentation on api.drupal.org just like we are now doing for the tpl.php files. Even I can write a regexp to find everything between {# and #}, and then assume that's an @file doc block and parse as normal. :)

also, adding tag

Also adding a note that we will need to update http://drupal.org/node/1354 when this is decided :)

Doh. cross-post.

Hm. I'd like to note that the suggestion in comment #1 is not quite the same as the issue summary: it has /** */ inside of {# #}. The version in comment #1 would actually be easier for the API module to parse, since it is already set up to parse documentation comments in /** */.

Also, I'd suggest in the issue summary that the second section about how to do in-line comments -- the {# #} should always be on their own lines for readability unless the comment is exactly one line long. I think that would make it a lot easier to read/scan.

Updated issue summary.

Added example from #1

Applied standards from #6 to issue summary. Thanks @jhogdon.

Let's post-pone this until front-end is in core. Having Doxygen index the templates would be nice, but I believe we should discuss that later on. There's more pressing things to think about :-) .

Isn't it relevant to discuss now? It seems like if we agree on how to do this now, when we convert the tpl files we can do it right the first time?

Agree, this is a policy we need to discuss then add to standards and follow.

Add inline comment

Updated issue summary to include jenlampton's stuff from first comment.

Also agree. Having already gone through and cleaned up lots of existing docs in the twig front-end branch, to conform to the current instructions for conversion, IMO, it is best to define this earlier than later. The current conversions have so far produced very inconsistent doc that takes a non-trivial amount of time to clean up and format, whereas if the person writing the conversion pays equal attention to the doc as they do the code conversion, following the instructions, there's much less formatting work to do later on. Futhermore, there will be solid examples to copy from, reference, read, and improve, so if they are all consistent now, bad doc habits and formatting will have less chance of perpetuating themselves.

There are very clear instructions in the documentation for converting now. I don't think the docs were written when the converting started, and I also don't think all the people working on them read all the documentation :)

I did a huge pass on docs updates over the weekend, cleaning up stuff and getting things back in order. But do you have a suggestion as to how to make things clearer, or where to write new docs for people to read?

If you can point me to where the docs are about twig conversion, I would be happy to review them. Also, if some standards for the comments at the top have in fact been adopted (which I would think should have happened on this issue or on another issue tagged "coding standards" so that those of us interested could comment on proposals?!?), we need to add them to the coding standards section of drupal.org/coding-standards somewhere.

So... where are the standards?

Right now the documentation we are using is specifically for converting theme functions to twig templates, and lives in a google doc:
https://docs.google.com/document/d/1zf7LOdms2x9iqA7b_9vMxw540vg1tT_9VOcm...

...but I'd love to create a d.o docs page somewhere but I'm not really sure where that should live, or what it should look like.
I started a page here but could use some guidance.

Thanks! That looks like the right place to put the page.

I fixed a couple of spelling errors on the page, and also here are a couple of notes on the standard docblock itself:

- @ingroup themeable => was misspelled themable [missing e] in the previous revision, but it looks like it's correct in the Google Doc.
- The first line of the docblock was not the same as our standard, so I updated it.

I also added a link to the standards for PHP template files on node/1354, and added a note that comments should wrap at 80 characters. But it looks good! I think we can call this issue fixed, since the standard has apparently been adopted and now it is also documented. Thanks!

I've reopened #1813240: Cleanup twig template documentation to fix any instances of misspellings of "themeable" in the twig sandbox front-end branch.