Documentation for devise-passkeys

[heliocola]

@tcannonfodder : here are a few formats for module/class documentation that I have seen and it can be used:

1. Very simple: no format, 1 to many lines of comments as needed:

   module Devise
   # All Passkeys sub-modules, models, classes, concerns etc are inherited from here.
   module Passkeys

2. Minimum format: one line for name, 1 to many lines for description:

   module Devise
   # Name: Devise::Passkeys module
   # All Passkeys sub-modules, models, classes, concerns etc are inherited from here.
   module Passkeys

3. Some format and more verbose: one line for name, one line for summary, 1 to many lines for a longer description:

   module Devise
   # Name: Devise::Passkeys module
   # Summary: All Passkeys sub-modules, models, classes, concerns etc are inherited from here.
   # This is the top level Passkeys modules and as such all sub-modules, models, classes, concerns etc
   # should be inherited from.
   # The folder structure is as follow:
   # ... add as much details as we need
   module Passkeys

My suggestion at this stage is to start with option 1 and move toward a more meaningful and long documentation. With that said, I have a draft PR #3 that makes the code compliant with rubocop.yml. If you think that is the way to go, I will submit it for review.

Or if you prefer a different format, I'd be happy to work on.

[tcannonfodder]

It fells counterintuitive, but I think starting with YARD-compliant docs (option 3?) would be the best move forward. Reasons being

• the code itself isn’t particularly difficult, so the documentation is for the purpose of all the modules
• Going straight to YARD would help with discovery because of RubyDocs, and IDEs could easily present the docs since it’s a common format
• The library is almost done (minus emergency registration & some potential helpers for analyzing credentials), so might as well get the docs up to snuff

[heliocola]

Got it. I was bit confused with the empty description and with RED CI (I confess that causes some anxiety)! I think the PR I have is not the direction you want to go, as my goal was to get Green CI.

If I am understanding correctly, the goal is to add meaningful (a few lines long) comment for each modules. Is that correct?

[tcannonfodder]

That is correct! Sorry about the confusion & lack of detailed issue title 🙈

reviewing your changes now!

[johalloran01]

We are creating separate pull requests for each section under the Documentation Milestone!

------WORDY BREAK DOWN BELOW, READ AT YOUR DISCRESSION---------

@tcannonfodder and I had a discussion about the best way to approach this issue. We determined that trying to write the documentation all in one issue/pull request would prevent us from effectively trouble shooting any issues we may run into after we begin addressing the documentation. It'll also prevent us from knowing which section we should start working on, amongst one another.

Here are the solutions we came up with:

• create a milestone for the documentation
• Begin with a top down approach to documenting each section.
• inside the milestone each section will have its own issue and pull request, that when initialized will represent the beginning of someone working on the documentation for that section. By doing this we know which section is actively being worked on and what issues are being raised in relation to that section. This will also enable us to trouble shoot and back track if any issues arise as we proceed through the process.
• We will be meeting next week to effectively label and organize which sections (comprised of specific individual files) we are creating documentation for, and divide up the work effectively!

[tcannonfodder]

Tentative sections:

• Registration
• Sessions (authentication)
• Reauthentication
• PasskeyIssuer
• Warden Strategies
• PasskeyAuthenticatable

~I'll try to get the YARD setup done tonight.~ (Done in https://github.com/ruby-passkeys/devise-passkeys/pull/8)

I wouldn't fret about making the documentation perfectly YARD formatted when you're working on it; we can do that at the end of the PR. The harder part will be actually writing useful documentation 😂😭

[tcannonfodder]

Added a set of issues in the milestone! https://github.com/ruby-passkeys/devise-passkeys/milestone/1

[heliocola]

IMO useful documentation is a long term strategy. First step is to have the first one! And we keep iterating on it for the foreseeable future! :-D

As more and more users start using the gem and asking questions, we will end up find ways to improve it! Also: today I know a lot more about passkeys concepts, so it is easier for me to describe it...

Rock solid idea into breaking this up. I have some draft documentation in my old laptop, but haven't pushed yet.

[tcannonfodder]

Sounds good; feel free to pick one of the documentation issues that haven’t been claimed yet 💪

RE: useful vs. initial documentation: I think given the size of the gem & the fact there are multiple folks working on this, we can get a useful set of documentation out of the gate. For example, #24 is a great example of a set of docs that are solidly baked, making 0.2 a very useful release when we’re done 😄