Docs for Arc and Working Rake Task #1532
Conversation
nicholalexander
changed the title
shoes-core/lib/shoes/arc.rb
Outdated
| # arc 200, 200, 100, 100, Shoes::PI, 0 | ||
| # @note Angle is the gradient angle used across all art elements. Angle1/2 are the angles of | ||
| # the arc itself! | ||
| # @author Jason Clark |
There was a problem hiding this comment.
Don't know that I deserve specific credit here--I probably just shuffled the class around from it's original location :)
| # @example A simple arc which describes the bottom half of a circle and uses the centered style. | ||
| # arc 200, 200, 100, 100, 0, Shoes::PI, center: true | ||
| # @example An arc which describes the top half of a circle. | ||
| # arc 200, 200, 100, 100, Shoes::PI, 0 |
There was a problem hiding this comment.
Love the examples, very helpful!
shoes-core/lib/shoes/arc.rb
Outdated
| # @param angle1 [Float] The first angle of the arc to the center point, in Radians, | ||
| # starting from the 3 o'clock position. | ||
| # @param angle2 [Float] The second angle of the arc to the center point, in Radians. | ||
| # @param [Hash] Style hash |
There was a problem hiding this comment.
I believe yard also supports describing the @option values that are supported in a hash (http://www.rubydoc.info/gems/yard/file/docs/Tags.md#option). Those seem worthwhile to consider listing out too.
There was a problem hiding this comment.
Cool, will fill out the options for the style hash.
There was a problem hiding this comment.
Hmm, a couple of problems on this one. Firstly the params aren't showing up in the yard doc because it wants them to be next to an initialize method.
Additionally, the options hash needs to be named in order for it to pick up and match against it.
class Blurgh
# @param thing [Integer] a thing!
# @param thing_hash [Hash] a thing hash which we want to have.
# @option thing_hash [String] :blurgh the name of blurgh
def initialize(thing, thing_hash)
end
end
I will have to dig deeper into yard to see if I can figure this out...
There was a problem hiding this comment.
Ah, didn't know that about it. I wouldn't worry on it for too long--if you can't find an easy way, we can table the options hashes until later (or never) and just roll forward with this now.
tasks/yard.rb
Outdated
| t.options = ['-mmarkdown'] | ||
| t.files = ['shoes-core/**/*.rb', 'README.md', 'LICENSE', 'CONTRIBUTING.md', | ||
| 'CODE_OF_CONDUCT.MD'] | ||
| t.options = ['-mmarkdown', '--no-private'] |
There was a problem hiding this comment.
So these are a good start, but I found generating locally that this gives me a bit better result:
YARD::Rake::YardocTask.new do |t|
t.files = [
'shoes-core/lib/**/*.rb',
'-',
'README.md',
'shoes-core/README.md',
'LICENSE',
'CONTRIBUTING.md',
'CODE_OF_CONDUCT.MD'
]
t.options = [
'-mmarkdown',
'--no-private'
]
It does a couple things:
- Only generates for the
shoes-core/libfolder, since we were picking up specs - Works correctly with the markdown files by putting them after a
-
How does that look to you @nicholalexander?
|
Sorry for dropping off for so long! Had some business travel, followed by holidays, but I'm back in the Shoes action in earnest now. Getting yard working again is really helpful--it was on my short list to look at soon, and this is a great first step. Few comments, nothing major, and this should be 🆒 to go after those. |
|
No worries at all, I was away for the holidays as well. Will make suggested changes! |
|
@jasonrclark - I took your suggested configuration and moved it into a yardopts file, that way you can either run |
nicholalexander
changed the title
|
@nicholalexander Is the only thing outstanding seeing what can be done about the hash options? Excited to get this landed so I can join in writing some docs as I go. 📚 |
also move info about radians in to class documentation.
nicholalexander
changed the title
|
Hey @jasonrclark - sorry for the delay, I was away for the long weekend. This should be good to go as it is now. I removed the params from the docs because those also weren't showing up. As it currently stands, yard is configured and working and the class has some initial documentation which generates correctly. If we want to solve the params and options problem, that could be done in another PR. Thanks! |
|
No apologies necessary--we're all volunteers here. Thanks for the tidy up, and here comes the merge 🚄 ! |
Trying to also make progress against #620.
Two things here:
when I ran
rake yardthe yardoc generation didn't generate any files. Maybe this was because I wasn't running it correctly? I was able to generate some of the documentation by modifying the rake task as here. However, we may want to add a .yardopts file so that running yardoc from the root works without requiring a rake task? This might also be required to get the docs on rubydoc - entirely not sure. I also added --no-private flag as per the comments in Document ALL the things #620.Made a first pass at adding in some docs for the Arc class where I feel sufficiently able to explain what's going on. I also moved a comment into the notes so that it is featured in the generated docs.
Completely not sure if this is helpful or not but thought I'd start on it and welcome any and all direction change!
best,
n