0

I've been reading about semantic versioning.

Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation.

So, does doccomments above the public methods of my library counts as declaring a public API?

class FooBar 
{
    /**
     * Does this and that and this
     * @param array $list
     * @return boolean
     */
    public function doSomething($list) ....
}
Adinan
  • 21
  • That depends: if you say in your versioning documentation that doccomments are a public API, then it is a public API, if you say that it is not a public API, then it is not a public API. – Jörg W Mittag Aug 27 '17 at 14:04
  • 5
    Show us where you got that quote, so that we can see it in context. Absent context, the quote seems self-evident, since semantic versioning is all about carefully controlling the public API so that you don't unnecessarily disrupt your users when you release an update. The code comments have little to do with that; it's the public function declaration that makes this function part of the public API. The only purpose that a comment might serve is a warning: "Don't use this method." But if that's true, then why declare it public in the first place? – Robert Harvey Aug 27 '17 at 14:04
  • @RobertHarvey Depends on the relationship between objects. Sometimes a public method is written intended to be used by another class of the library, not the user. – Adinan Aug 28 '17 at 15:34
  • If it's used internally by the library only, it does not need to be made public. – Robert Harvey Aug 28 '17 at 16:29

1 Answers1

1

For semantic versioning, it does not really matter if such a comment is seen as as part of the public API or not. What matters is what a change to the comment means to the version numbers.

Quoting the main rules for version numbers from the former link:

Given a version number MAJOR.MINOR.PATCH, increment the:

  1. MAJOR version when you make incompatible API changes,

  2. MINOR version when you add functionality in a backwards-compatible manner, and

  3. PATCH version when you make backwards-compatible bug fixes.

So when you just change the comment in your code, and nothing else, and you plan to republish your lib, the question is which of the 3 version number parts has to be incremented?

First, such a change is almost never an incompatible API change, since you did not change anything in the behaviour of the library - no working code which relies on that library will factually break. So, there is no need to increment the MAJOR part (see comment from @JörgWMittag for exceptions from this case).

Second, if the comment now mentions a functionality of the API which was formerly undocumented (and not obvious from the signatures or context), then the change of comment makes a new functionality available to the users, but in a backwards-compatible manner. That could justify an increasement of the MINOR part. Also, when you add a "deprecated" remark to the comment of a function, the SemVer rule #7 states clearly, MINOR must be increased.

If the comment is just an improvement of the description or corrects something which was documented wrong, then increase the PATCH number.

Community
  • 1
Doc Brown
  • 206,877
  • 1
    This is an interesting interpretation of the question that hadn't occurred to me. I interpreted it as "does a doc comment make the function part of the public API", whereas your interpretation is "is the doc comment part of the public API". BTW, I disagree with your assessment that a change to the doc comment cannot be a backwards-incompatible API change. If the change in the doc comment declares a certain usage illegal that was allowed before, then that is an incompatible change. Yes, in an ideal world, such changes would be expressed in the type system, but alas, people still use inferior … – Jörg W Mittag Aug 27 '17 at 16:50
  • … languages like Java, where not every contract can be expressed as a type. (And I happily include myself in the "inferior languages user camp" with my affinity to Ruby.) – Jörg W Mittag Aug 27 '17 at 16:51
  • @JörgWMittag: interesting point of view about incompatible backward changes. Does such a comment really break anything? I would typically argue if a function usage is declared as "illegal" (=causing hard technical problems) in a sucessor of V1.0.0 - without any code change in that sucessor, than it was already illegal in V1.0.0, undocumented or not. Code which relies on V1.0.0 has to be changed as well for avoiding anything "illegal" happen, not just after switching to the successor. Or do you mean "illegal" in a different sense? – Doc Brown Aug 27 '17 at 17:28
  • I am thinking about some examples from the Ruby world. When JRuby started to gain traction, there were a lot of corner cases, where programs behaved differently on MRI and JRuby, for each and every one of those cases, the developers had to decide: do they change JRuby or do they change the documentation or MRI (which basically is also the standard library spec). Every time they decided to change the documentation of MRI, they potentially made some existing programs invalid according to the spec, yet not a single line of MRI source code had changed. – Jörg W Mittag Aug 27 '17 at 17:39
  • This happened mainly around thread-safety of data structures: a lot of programs exhibited race conditions on JRuby that were impossible to occur on MRI, because MRI is incapable of executing Ruby threads in parallel. By declaring that certain operations aren't guaranteed to be atomic, those programs which "accidentally" worked on MRI were officially declared broken, without an actual code change in MRI. – Jörg W Mittag Aug 27 '17 at 17:41
  • I can imagine a similar scenario without involving multiple independent implementations, in cases where you want to restrict usage of your API in order to enable future refactorings. For example, you have an sqrt function which ignores the sign of the input, but you want to keep your option open to replace it with a different algorithm that will break on negative numbers. – Jörg W Mittag Aug 27 '17 at 17:43
  • @JörgWMittag: see my edit. – Doc Brown Aug 27 '17 at 19:29
  • @DocBrown "if the comment now mentions a functionality of the API which was formerly undocumented (and not obvious from the signatures or context), then the change of comment makes a new functionality available to the users, but in a backwards-compatible manner. That could justify an increasement of the MINOR part" So yes, it does. Thank you. – Adinan Aug 28 '17 at 16:38