Improve documentation for DSL attribute hash keys [RFC] [Guides]

[Ashton-W]

I want to improve the Guides for the DSLs. Currently they don't list the acceptable hash keys, there are only examples from which you can gleam this important information.
https://guides.cocoapods.org/syntax/podspec.html#source

I'm trying to find a good pattern to get this information into the documentation system, then we will also have to update guides.cocoapods.org to format and include it. Right now I'm just using yard to see how it picks up the comments.

Idealy, we shouldn't have to repeat ourselves. Where we define the options should be where the documentation is. I'm finding it hard to do this, and I'm not happy with the @overload usage here.

🐦 @orta

[segiddins]

Boolean?

[segiddins]

I like this! I personally feel overload is pretty spot on here.

[Ashton-W]

I'll continue on this path then, unless someone has a better idea of where and how to put the comments for the keys.

[Ashton-W]

Requesting more feedback.

There is more room for improvement in other areas where we rely on examples, but I'll get to those in other PRs.

Now to try and get it in guides.

[orta]

don't worry about getting it in the guides, every CP release it will be automatically migrated in,

[orta]

Overall looks good to me, more docs is 👍

[neonichu]

@Ashton-W good work 👍

[Ashton-W]

@orta guides doesn't surface these particular documentation tags yet

[segiddins]

@Ashton-W because we haven't cut a new release of CocoaPods yet ;)

[Ashton-W]

I'm running guides locally with the Core gem pointing to my fork. @Overloads and @options don't show up.
Am I missing something?

[segiddins]

You've updated the Core submodule in gems ?

[Ashton-W]

Yes. Other changes are reflected in the generated site:

[segiddins]

OK, thanks for opening the issue over there, I'll try and take a look before I release the 0.39 beta