In a Puma issue, I mentioned the issue of conditionally defined methods, where the source actually has two definitions for a given method. Since most doc systems won't list two definitions of the same method, what I've seen done is define two methods, and alias then remove. The doc is clear, and it doesn't add much code.See doc at Server#closed_socket?, the closed_socket_no_cork? method right below it, and the comments I attached.Note that alias_method needs to be used with send, otherwise the doc system interprets it.
Attributes - I've always preferred to divide code into attributes and methods, as I prefer what's shown as methods to perform actions, rather than get/set values. YARD has a syntax for tagging a method as an attribute, and I've added it where appropriate. Also, getter methods cannot have parameters. Examples - backlog, current, pool_capacity, running, etc. Current docs at puma.io show them as methods.
Made a couple of code changes, ThreadLocalKey constant to the top, remove def self.current and placed it in the class << self block, use fetch instead of tertiary ? : statement.
Mentioned previously. Current puma.io site has the most recent release docs in a 'puma' folder. I'm fine with adding 4.3.6 docs to a 'puma4' folder.
YARD allows one to diff two gems in terms of API. It shows added, modified, & deleted methods, classes/modules, and constants. That info is how I added the 'version' tags to all the new methods in 5.0.0. It would be relatively easy to create an API ChangeLog md file, and it could link to all the added items. Note that if an added item was deleted in a later version, the link would break.
There were several weeks where I wasn't very active in Puma, working on other things. I came back to it, and really wished the docs were a bit better. That's where all this interest in docs is coming from. One doc I might work on is 'A socket's travels through Puma...`
nateberkopec
commented
4 years ago
@nateberkopec
Been looking at more doc updates for Puma. I started with server.rb. Revised doc is here at: https://msp-greg.github.io/puma.io/puma/Puma/Server.html
The code is at: https://github.com/MSP-Greg/puma/commit/adce6b39c65c64d6c097f595b45594e9b050c8cb
Changes:
In a Puma issue, I mentioned the issue of conditionally defined methods, where the source actually has two definitions for a given method. Since most doc systems won't list two definitions of the same method, what I've seen done is define two methods, and alias then remove. The doc is clear, and it doesn't add much code.See doc at
Server#closed_socket?, theclosed_socket_no_cork?method right below it, and the comments I attached.Note thatalias_methodneeds to be used withsend, otherwise the doc system interprets it.Attributes - I've always preferred to divide code into attributes and methods, as I prefer what's shown as methods to perform actions, rather than get/set values. YARD has a syntax for tagging a method as an attribute, and I've added it where appropriate. Also, getter methods cannot have parameters. Examples - backlog, current, pool_capacity, running, etc. Current docs at puma.io show them as methods.
Made a couple of code changes,
ThreadLocalKeyconstant to the top, removedef self.currentand placed it in theclass << selfblock, usefetchinstead of tertiary? :statement.Mentioned previously. Current puma.io site has the most recent release docs in a 'puma' folder. I'm fine with adding 4.3.6 docs to a 'puma4' folder.
YARD allows one to diff two gems in terms of API. It shows added, modified, & deleted methods, classes/modules, and constants. That info is how I added the 'version' tags to all the new methods in 5.0.0. It would be relatively easy to create an API ChangeLog md file, and it could link to all the added items. Note that if an added item was deleted in a later version, the link would break.
There were several weeks where I wasn't very active in Puma, working on other things. I came back to it, and really wished the docs were a bit better. That's where all this interest in docs is coming from. One doc I might work on is 'A socket's travels through Puma...`
Anyway, no hurry, let me know what you think...