Document ALL the things

[PragTob]

As we want to be a nice easy to use toolkit we need documentation. Lots of it.

• Write rdoc for classes/public methods
• Appropriately mark private methods as such so they are not included in the rdoc
• Update the manual
• Ensure Yard generation to http://www.rubydoc.info/github/shoes/shoes4 is looking 👌

This is mostly here to remind us of it for rc1 4.0. Some methods already have rdoc comments which is great 👍

The most important thing to document is the DSL module.

As a side note, I'm on the pro side of code should be so readable that it does not need comments. Documentation, especially for a library is different though. Especially a beginner library. Lots of people out there wouldn't even dare to look at source code to see how something works - I was just like that when I started and years after that. And people shouldn't have to do that. Good up to date documentation is vital to the success of a project imo.

[ybur-yug]

@PragTob I would love to start working on this, and also commented w.r.t Rubocop violations. I am working on a project for a nonprofit that needs cross-platform support and this looks more promising than electron for my needs (quite simple). So, since I'll hopefully be using shoes4 (so far have used 3.x, but want to upgrade) I would love to start contributing.

[jasonrclark]

❤️ @ybur-yug that sounds great! Let us know if you need any help in getting started on either of those. They both seem like great points to start from.

FWIW, the manual has been extracted to it's own separate project, so if you're wanting to modify things in that you'll want to PR over there. https://github.com/shoes/shoes-manual

[ybur-yug]

Thanks @jasonrclark! I've got a bit of a busy early week w.r.t my regular work, but should be able to dive in relatively soon. I was thinking of starting with Rubocop because it will force me to go through the guts of the codebase (which is obviously quite large). With the other simple 'newcomer friendly' pieces like tests on somewhat isolated classes would get a lot easier with that done.

Thoughts? I'm pretty open to being instructed, this is obviously yall's baby :)

[jasonrclark]

You're absolutely right that Rubocop will get you some broad exposure to the code, and get you running tests and learning where things stitch together.

I'd recommend finding a set of changes--either fixing the same problem across the library, or fixing all the problems in a single class--and then PR'ing that individually. Smaller changesets will be easier to get reviewed, tested and merged.

Shoes is a labor of love for all of us involved, so no worries on timing. We all just do what we can when we can, and are excited for every contribution!

[PragTob]

:) Hi @ybur-yug welcome - speaking of time yes, I also sometimes don't manage to take a look for some days but then I rely on @jasonrclark and or patience :)

Rubocop seems like a good place to start, though with Rubocop it's often about style and not actively involved changing things. Hence I recommend to also take a stab at small bugs or changes or writing specs, that's more involved with how the code actually works :)

Tobi