Refine configuration design docs

[pellared]

Why

Get rid of:

• unusable exported API
• unnecessary noise in GoDoc

Make the docs a little less confusing.

Reference: #536 (comment)

What

Changes in configuration deisn docs.

Unexport Apply method

I see no reason to export Apply the method in Option interfaces.
Unexporting the method is also an additional safety net if someone accidentally exports the config struct.

Example in practice: open-telemetry/opentelemetry-go-contrib#750

Change T* to T

I find that using T* for a generic type name may be confusing. Someone may think it is *T when reading quickly (pointer to T). I suggest simply using T as a placeholder.

[pellared]

Can someone add Skip Changelog label, please? 😉

[MrAlias]

The scope of the PR has crept beyond the initial scope of just addressing the content of the configuration style guide. I think the generalized markdown formatting changes are a great addition, but can we move them to another PR?

[pellared]

a great addition, but can we move them to another PR?

Do you have a strong opinion here? 😉 I won't be able to fix it today and I think we would lose more time on the PRs than it is worth.

[MrAlias]

a great addition, but can we move them to another PR?

Do you have a strong opinion here? I won't be able to fix it today and I think we would lose more time on the PRs than it is worth.

Without splitting things out this PR needs to have all the approvers re-evaluate their approval as the scope and content have changed. I think it is probably the best approach to revert the changes here and add them to another PR. Once the revert is done here we can merge this.

[MrAlias]

We have a bit of an honor system around re-requesting reviews after substantive changes have been made to a PR: https://github.com/open-telemetry/opentelemetry-go/blob/main/CONTRIBUTING.md#how-to-get-prs-merged

If you want to keep the PR as is, please re-request reviews.

[pellared]

the best approach to revert the changes here and add them to another PR. Once the revert is done here we can merge this.

Done 😉 I will create a PR for reformatting all Go markdown code blocks once this is merged.

[codecov]

Codecov Report

Merging #1841 (b6b8b11) into main (24a9162) will decrease coverage by 0.0%.
The diff coverage is 0.0%.

@@           Coverage Diff           @@
##            main   #1841     +/-   ##
=======================================
- Coverage   78.6%   78.5%   -0.1%     
=======================================
  Files        137     137             
  Lines       7298    7298             
=======================================
- Hits        5739    5736      -3     
- Misses      1315    1316      +1     
- Partials     244     246      +2     

Impacted Files	Coverage Δ
sdk/resource/resource.go	64.2% <0.0%> (-3.6%)	⬇️
sdk/trace/batch_span_processor.go	82.4% <0.0%> (-1.6%)	⬇️
exporters/trace/jaeger/jaeger.go	92.8% <0.0%> (+0.5%)	⬆️