-
-
Notifications
You must be signed in to change notification settings - Fork 875
Annotating code samples with file names #12
Comments
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. I'm confused by your example @stevekinney, since globals are to be deprecated, but I would include the |
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.) |
@stevekinney excellent point. my thoughts:
|
i would like to , but their are several different and potentially confusing manifestations of pods. Maybe not yet? ... @tomdale thoughts? |
@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. |
#13 is tangentially related. How do we want to call various controllers, routes, etc. outside of code samples? Refer to them by file name? |
I don't have a strong opinion either way. All I'd ask is:
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. |
Related, maybe it's smart to hint people to use |
Does the POC of Ember cli work with a pods structure? http://jsbin.com/zonuhofufo/1/edit?html,output |
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
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:
This should do three things:
|
@trek Wow, I really like that idea. |
Can you rope in @gregone and/or @danmcclain to help with the visual design and CSS for a change like this? |
@trek 👍 had thought of something similar myself, but didn't know about the meta data thing. |
@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 |
👍
|
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 |
👍 |
moved to #30 |
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:
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
The text was updated successfully, but these errors were encountered: