Public?
trans opened this issue · comments
I don't quite get Public: if a method is public via the Ruby itself, is it not a public method? I mean how would it make any sense to do:
class Foo
private
# Public: foo stuff
def foo
....So why do we need this for methods?
A method "could" be "private" as in not part of the public API of whatever you're documenting but not declared as private in code. It's not entirely synonymous with the private keyword of the language. For example when I tomdoc my CoffeeScript all my methods are technically public however I put Public: when the method is part of the API a developer will be interacting.
But that's the other way round. In fact I would much prefer that --let me make methods Private: otherwise assume they are public,
But that's the other way round. In fact I would much prefer that --let me make methods
Private:otherwise assume they are public,
+1
Explicit Private: sounds better than Public: +1
Explicit Public: makes you think before you add something to the public API though.
+1 for explicit Private: otherwise assume Public:
The biggest reason TomDoc is private by default is to make the Public ones stand out. This is extremely important for new contributors to be given a reminder that any changes to signature or return type should be made with extreme care. It's an ever present reminder that changes to these methods are especially sensitive, as they comprise the public API.
In addition, public APIs are generally much smaller than all available methods, and methods should be made public only after careful thought. Making everything public by default means that you're much more likely to casually make methods public that probably shouldn't be.
My API's use Ruby's own private/protected/public mechanisms. I don't think I've ever had occasion to make some method "Internal" even though it was actually a public method. So to me it seems mostly a waste of typing, and I also find it somewhat distracting from the description. Personally, I'd probably prefer it if there wasn't public vs. private methods and it was in fact just a doc detail, but that's not the way it is, so it feels rather redundant. In fact, not that I am in support of it (I tried to argue it should be a doc detail only), but upcoming versions of Ruby are supposed to support public/private constants. So the use of Public/Internal for those will seem redundant in the future too.
@trans Most of the time you don't explicitly type public :my_method, though. This makes making method public a very explicit action.
Also, I've seen this several times:
class SomeClass
def some_method
end
private
def some_other_method
end
# Tons of other methods
def yet_another_method
end
endWhen I just look at yet_another_method, I have now idea if the author wrote a public in between that and the last private, unless I read through all the code. I want to just look at the function and instantly know if it's in the public API or not.
Also, there are times when you may want public methods (ruby-wise) to be in the internal API. For instance, in my context-io library, every class has a from_json class method that I use internally in the library to convert from the raw JSON I get from the HTTP API to the ruby object. I don't see how this is useful for the user, so I don't provide it as a part of the public API. However, some classes generate other objects (for instance, a Thread has several Messages, so they need to be callable across the classes, which makes making them private tricky (at least without some hacks).
That's true. Sometimes though you see libraries with just the opposite issue, they have a few private methods and a bunch of public ones. It just depends on the library/application.
I've thought on occasion that Ruby might have been better off if it used explicit visibility in the definition of all methods, e.g.
class SomeClass
public some_method
end
private some_other_method
end
private yet_another_method
end
end
+1 @trans, I like that.
-1 @trans, looks like Java.