Better documentation in pins_arduino.h [imported]

[cmaglie]

This is Issue 1055 moved from a Google Code project.
Added by 2012-09-30T08:09:30.000Z by wes...@gmail.com.
Please review that bug for more context and additional comments, but update this bug.

Original labels: Type-Enhancement, Priority-Medium

Original description

What steps will reproduce the problem?

1. There have been requests for a tutorial on modifying pins_arduino.h to meet the needs of custom-designed boards.
2. pins_arduino.h is not well documented internally.

The attached diffs add a bunch of comments (only! No actual code changes!) to variants/standard/pins_arduino.h explaining what it does and approximately how it works. This should make it a bit less confusing for a moderately skilled programmer to make their own variant.

[NicoHood]

We should probably add a guideline to the wiki. Which definitions are required, or should be added so every library can work. I dont think that we need to add this to the file itself.

[matthijskooijman]

Yeah, I would like to see this as well. It's been on the TODO list in my head for a while now, I just haven't found the time for it yet so far (and probably wont' in the near future).

[per1234]

I agree about the wiki. Comments in the code are fine too but I think it should also be documented separately. Documenting the standardized things that are expected in any variant definition would be helpful to ensure that hardware packages follow a uniform standard.

I think the Hardware Specification page of the wiki would be the most appropriate location. Any thoughts on that?

EDIT: I found a better issue report for the topic of adding this documentation to a wiki page here: https://github.com/arduino/Arduino/issues/4141. Let's continue any discussion of that subject over there.