Does doc comments count as declaring a public API?

Question

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) ....
}

Answer 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.