Best practice for documenting ports / peripherals?
The short answer is "whatever makes sense to you and the rest of your team". 

Since that isn't very informative as far as how to implement something, ultimately communicating the intended behavior is the point. 

Comments can't be tested. They are a risk for becoming outdated and unmaintained in general. Comments can help though with understanding the why. There are other smart engineers like yourself that will figure out the how by reading the actual source. 

I would recommend doing some research on writing a Hardware Abstraction Layer (HAL). 
This does a couple of things. 


A HAL will show in one file what pins are being used for what purpose. It might also be advisable to indicate which pins are not used (they come in handy for debug/bringup of new designs, so take the extra two minutes to document unused ports/pins now and save yourself 15 minutes in searching for them when you need them.)
By writing a HAL, the code that uses your HAL (the embedded application) won't care what the actual pinout is. This will ease in portability when (not if) you need to change micros in that the brunt of the work that would have to take place is in the HAL itself and not in your application. 


In summary, there's nothing wrong with comments, but the executable code is the only thing that matters in terms of what is actually happening.