(#267) Don’t show “Public X” header without contents #314
Conversation
danielparks
force-pushed
the
better_public_private
branch
from
39404c7 to
72f270e
Compare
danielparks
force-pushed
the
better_public_private
branch
from
72f270e to
83ef641
Compare
danielparks
force-pushed
the
better_public_private
branch
from
83ef641 to
d14638c
Compare
danielparks
force-pushed
the
better_public_private
branch
from
d14638c to
3991e75
Compare
|
I realized that it was a lot clearer to pull |
| # @param [String] path The full path to the template file. | ||
| # @return [ERB] Template | ||
| def self.erb(path) | ||
| if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0') |
There was a problem hiding this comment.
I wrote this, but later on I realized you could also write it with the if outside of def so it's only ran once, though it probably doesn't matter much.
There was a problem hiding this comment.
Hm… I thought about it, but I’m inclined not to since it ends up duplicating the doc comment. Or maybe I should just put the docs above the outer if if I do that? Pretty sure the performance difference will be negligible.
danielparks
force-pushed
the
better_public_private
branch
2 times, most recently
from
dbf2c55 to
1681e77
Compare
Previously, the “Public X” header would be displayed if there were any
private X regardless of whether there were any public X.
For example, having a private function would make both the “Public
Functions” and “Private Functions” headers appear, even if there weren’t
any public functions.
This changes it so that there are three conditions:
* **Only public X:** no “Public” or “Private“ headers are displayed;
the X are listed with links to their documentation. (Public is
implied.)
* **Only private X:** a “Private X” header is is displayed with a list
of X. There are no links to documentation for private APIs.
* **Both public and private X:** both “Public X” and “Private X”
headers are displayed. The public Xs are listed with links to their
documentation; the private Xs are just listed with no links.
In other words, if there are no private Xs, then it just lists the
public once. Otherwise, it splits them up under public/private headers
but avoids showing a header if it’s contents will be empty.
This also radically simplifies and removes a bunch of boilerplate code
around rendering these sections.
danielparks
force-pushed
the
better_public_private
branch
from
1681e77 to
64aa800
Compare
| # | ||
| # @param [Optional[String]] Name of the group to set | ||
| # @return [String] Name of the group | ||
| def self.group_name(name = nil) |
There was a problem hiding this comment.
Thoughts about splitting the functionality in self.group_name() and self.group_name=(name)? Would that work?
Same comment applies to yard_types.
There was a problem hiding this comment.
I actually tried doing
class << self
attr_accessor :group_name
attr_accessor :yard_types
endbut I ran into a few problems. One was that it interpreted yard_types = [...] as trying to set a local variable instead of calling a class method, but maybe I could have called self.yard_types = [...].
I wanted it to look more like functions like attr_accessor since I figured that would feel more natural, but it did seem inconsistent with the way Ruby does things elsewhere.
I don’t have a real good sense for the Ruby Way anymore… been writing other languages for too long.
There was a problem hiding this comment.
Fair enough. I suppose this is good enough.
| .map(&:to_hash) | ||
| .map { |i| new(i) } |
There was a problem hiding this comment.
You can combine both maps
| .map(&:to_hash) | |
| .map { |i| new(i) } | |
| .map { |i| new(i.to_hash) } |
| # @return [Array] list of items | ||
| def self.items | ||
| yard_types | ||
| .flat_map { |type| YARD::Registry.all(type) } |
There was a problem hiding this comment.
TIL about https://ruby-doc.org/core-2.7.1/Enumerable.html#method-i-flat_map. Neat!
Previously, the “Public X” header would be displayed if there were any private X regardless of whether there were any public X.
For example, having a private function would make both the “Public Functions” and “Private Functions” headers appear, even if there weren’t any public functions.
This changes it so that there are three conditions:
In other words, if there are no private Xs, then it just lists the public once. Otherwise, it splits them up under public/private headers but avoids showing a header if it’s contents will be empty.
This also radically simplifies and removes a bunch of boilerplate code around rendering these sections.