Automattic / Gravatar-SDK-iOS

Gravatar SDK is a Swift library that allows you to integrate Gravatar features into your own iOS applications.
https://gravatar.com
Mozilla Public License 2.0
36 stars 1 forks source link

Improve documentation organization #334

Open andrewdmontgomery opened 1 month ago

andrewdmontgomery commented 1 month ago

Closes #

Description

Adds some organization to the Gravatar module's documentation.

Testing Steps

andrewdmontgomery commented 1 month ago

I saw that we were exporting Gravatar from GravatarUI, and this was allowing us to link symbol documentation in GravatarUI to various symbols in Gravatar.

But the downside of that approach is that the GravatarUI documentation then contains all of the Gravatar symbols, making it much harder to find and understand the symbols from GravatarUI.

So I've removed that export, and made adjustments to a few documentation entries in GravatarUI that were linking to Gravatar symbols (which won't work without exporting them in GravatarUI).

It's a trade-off:

There's another challenge with having all documentation in the GravatarUI module. The more formatting, images, etc. that we add to Gravatar documentation, the further it will drift from whatever gets automatically generated in the GravatarUI module. Put another way: if it is worth adding formating to the Gravatar module documentation, it is also worth adding that same formatting again to the Gravatar module documentation that is included with the GravatarUI module. That's twice the work. We could potentially automate some of it.