search

mojombo / tomdoc

A flexible code documentation specification with human readers in mind.
333 stars 47 forks source link

Visibility inheritance #38

Closed dasch closed 12 years ago

dasch commented 12 years ago

Would it make sense to have visibility inherit from classes to methods? So a method defined in an Internal class would default to being Internal as well. I'm really not digging having to write that prefix in all my method docstrings.

mojombo commented 12 years ago

One of the biggest aims of TomDoc is to be easily human readable and understandable in the code file. By inheriting properties like this, it would become extremely easy to overlook the inheritance (since it's only listed at the top of the file). I like that TomDoc is very explicit about the nature of each method. I think a tiny bit of extra thought and typing is warranted while carefully crafting code.

dasch commented 12 years ago

My problem with it is that I don't feel that objects should have both "internal" and "public" methods mixed together, but rather that objects as a whole can either be seen as part of the public API or internal and non-public. Does it make sense to have some public (from Ruby's perspective) but "internal" methods on an object that's part of a public API? It just doesn't seem necessary.