Annotating code samples with file names

[stevekinney]

Do we have a policy on annotating our code samples with file names?

In #11, it looks like we're using the traditional structure (e.g. // app/controllers/comments.js). But, in #8, we're using the pod structure (e.g. // app/post/route.js).

We should probably standardize on one.

I'm also wondering if we should include them at all for code samples where the file name doesn't really matter. For example, in the section on routes, we a route like this:

App.GoodForNothingRoute = Ember.Route.extend({…});

Should we bother making up a file name in this case? (I don't really care as long as we all decide to do the same thing.)

/cc @joostdevries and @locks

[locks]

Thanks for the ping!

I was actually instructed to open a new RFC for the pod structure so all the details can be hashed out.
This will enable ember-cli to then make pod structure the default, which IIRC is the current intent.
That's my rationale for using it in the file paths.

I'm confused by your example @stevekinney, since globals are to be deprecated, but I would include the
file path anyway, it's very easy to get lost otherwise if you're new to it.
I've also been including the imports and anything i feel necessary (e.g. https://github.com/emberjs/guides/pull/8/files#diff-98f6b706ad0759bf694f2cb81ce0d495R74) to make it self-contained.

[stevekinney]

Sounds good. (Yea, a big point is to get rid of the globals—I was only using it as an example where the file name might not be important.)

[joostdevries]

@stevekinney excellent point. my thoughts:

• use foo and bar for pointless stuff.
• whether or not we advise pods in the guides is something I'd like @tomdale and @stefanpenner s take on.

[stefanpenner]

whether or not we advise pods in the guides is something I'd like @tomdale and @stefanpenner s take on.

i would like to , but their are several different and potentially confusing manifestations of pods. Maybe not yet? ... @tomdale thoughts?

[locks]

@stefanpenner I'll open an RFC for pod structure this week as suggested by @wycats, so we clear it up. Sounds good?

[stefanpenner]

@stefanpenner I'll open an RFC for pod structure this week as suggested by @wycats, so we clear it up. Sounds good?

yes. Also, relevant POD related ember-cli issues: https://github.com/ember-cli/ember-cli/labels/pod Worth reviewing for the RFC.

[stevekinney]

#13 is tangentially related. How do we want to call various controllers, routes, etc. outside of code samples? Refer to them by file name? controller:application? Keep the current format?

[tomdale]

I don't have a strong opinion either way. All I'd ask is:

1. Make sure the guides and Ember CLI generators are in alignment.
2. Make sure any remaining issues with pods are hashed out.

If in doubt, let's start with non-pods and switch over. Versioned guided give us a lot more flexibility to change in the future. I don't want this guide revamp to end up getting blocked on pod implementation details.

[joostdevries]

Related, maybe it's smart to hint people to use ember generate wherever possible.

[nicolechung]

Does the POC of Ember cli work with a pods structure? http://jsbin.com/zonuhofufo/1/edit?html,output

[trek]

I have thoughts on where file names should go. http://commonmark.org/ defines the area we normally put the language label in "fenced code" as simply "metadata".

So, where we normally put

```javascript
var someCode;

Could actually contain any data we'd like. We have a custom highlighter that outputs particular markup/styles for specific languages.

The spec allows you to put any meta data in that location. Language is just a common use.

Instead of comments to denote file names, I'd prefer if we did this:

```app/templates/foo.hbs
{{rock-on}}

This should do three things:

• continue to detect bare named language fences
• begin to detect language name from file path fences
• output nice markup/style that decorates an HTML code block something that shows file location

[stevekinney]

@trek Wow, I really like that idea.

[trek]

Can you rope in @gregone and/or @danmcclain to help with the visual design and CSS for a change like this?

[locks]

@trek 👍 had thought of something similar myself, but didn't know about the meta data thing.

[joostdevries]

@trek Looks amazing. I actually think the original issue here has been resolved (we will not use POD syntax for now). Maybe it's best to either rename this issue or close & open a new one for the new code blocks

[danmcclain]

How's something like this (don't mind the colors for now...unless you like them, then it was intentional 😉)

[locks]

👍
On 5 Mar 2015 18:45, "Dan McClain" notifications@github.com wrote:

How's something like this (don't mind the colors for now...unless you like
them, then it was intentional [image: 😉])
[image: ember js - templates the application template 2015-03-05 13-45-05]
https://cloud.githubusercontent.com/assets/144138/6511903/e7978fd2-c33d-11e4-9135-4b579526f74e.png

—
Reply to this email directly or view it on GitHub
#12 (comment).

[danmcclain]

The markup is super basic for it too, all we have to add is

<thead>
  <tr>
    <td colspan="2">File name</td>
  </tr>
</thead>

To the top of the <table> generated by the highlighter. The screenshot I posted was one without any styles applied. We can tweak the look futher if needed

[joostdevries]

👍

[trek]

actually think the original issue here has been resolved

moved to #30