steemconnect-firebase-function with a new documentation: why did I use MkDocs instead of JSDoc or Typedoc?

in utopian-io •  last year  (edited)

docs

Details

New documentation is based on MkDocs and Material for MkDocs tools. They convert markdown into good looking static website with search option.

I've updated and added the Authentication with Angular tutorial to the documentation. It was published on Utopian some time ago, but wasn't correct for [email protected]. As it is impossible to edit posts older than 7 days on Steem, I had to add edited version directly to the documentation.

New documentation contains description and example usage of every function from the library. It also includes every custom interface and type used in the steemconnect-firebase-functions.

There is also a Glossary of terms that I use widely in the library.

Components

The documentation covers the entire library - every function, interface and type. Among that, it covers a tutorial, and example usage of library's functions.

Diff

A lot has been changed, because the library has changed. Difference between steemconnect-firebase-functions 1.x and 2.0 is huge. Thus, it turned out that my plan to keep JSDoc (or swap to Typedoc) wasn't possible to achieve. Why?

In the new version of library I make heavy usege of curried functions and object destructuring in functions parameters. It doesn't cooperate well with JSDoc or Typedoc, so I gave up my plans to generate API reference from in-code documentation.

Instead, I decided to use MkDocs + Material for MkDocs with my custom color palette. I had to rewrite everything, but I think it was worth it - new documentation is "clean and lean".

Curried functions also forced me to change the way parameters and return value of the functions is described. Now, if necessary, it is two steps based.

Another difference, of course, is that I documented functions that weren't available at all in version 1.x, namely:

  • pipe
  • combine
  • createOperation
  • createComment
  • createCustomJson
  • createDeleteComment
  • broadcastDeletion
  • checkOAuth2Error
  • isAccessTokenError
  • isAccessTokenExpiredError
  • isAccessTokenInvalidError
  • isAccessTokenRevokedError
  • isRefreshTokenError
  • isCodeError
  • combineCommentWithOptions
  • createBroadcastableVote
  • createBroadcastableComment
  • createBroadcastableCommentWithOptions
  • createBroadcastableCustomJson
  • createBroadcastableDeleteComment

Links

New documentation is hosted on the Github Pages:

You can also read it directly on the Github repo:



Posted on Utopian.io - Rewarding Open Source Contributors

Authors get paid when people like you upvote their post.
If you enjoyed what you read here, create your account today and start earning FREE STEEM!
Sort Order:  

Your contribution has been approved.

Thanks


Need help? Write a ticket on https://support.utopian.io.
Chat with us on Discord.

[utopian-moderator]

·

Hey @ms10398, I just gave you a tip for your hard work on moderation. Upvote this comment to support the utopian moderators and increase your future rewards!

Thank you very much for this tool, I just found it, but it is what I need. So, I'm reading to understand :)

Hey @jakipatryk! Thank you for the great work you've done!

We're already looking forward to your next contribution!

Fully Decentralized Rewards

We hope you will take the time to share your expertise and knowledge by rating contributions made by others on Utopian.io to help us reward the best contributions together.

Utopian Witness!

Vote for Utopian Witness! We are made of developers, system administrators, entrepreneurs, artists, content creators, thinkers. We embrace every nationality, mindset and belief.

Want to chat? Join us on Discord https://discord.me/utopian-io