hmm, commit and commit_all do return an Object. It just so happens that the object is a String.

The documentation could definitely use some improvement. I have gotten that started in #448.

I am hesitant to change an interface that has been in place for so long with out a major version bump.

Thoughts?

To be clear, the documentation indicates it should return a Git::Object (which Git::Object::Commit is), rather than any ruby object. I would argue that anybody expecting a string at this point would be developing against an undocumented "feature" and shouldn't expect that to remain the case.

Having said that, I understand the concern about breaking existing APIs without a major version bump, so I can see arguments for both.

While this change does more accurately reflect the documentation and I feel is more intuitive than the current return value, I would be fine holding it for the next major version (I would still like to see this in a future version) with the caveat that the documentation be updated to reflect the current return value (which I would be happy to contribute to).

I wonder if the current state of generated docs for this project (where by default, everything returns a Git::Object) represents a bug in Yard? Yard documents that:

YARD defaults to displaying (Object) as the default return type of any method that has not declared a @return tag

However, it appears this Object is evaluated within the main module of the project (for example, the Git module for this project). Because of this, the return type Object is linked to Git::Object not because the documentation changed, but merely by the presence of Git::Object.

Nesting the Object class into a submodule does not have this behavior.

Removing Git::Object results in YARD documenting Object without a link, implying ::Object.

What do you think about this overall plan to deal with this issue? These steps would be done in this order:

1. Immediately add a .yardopts file that sets the default return type of any method that has not declared a @return tag to ::Object. This can be done by including --default-return ::Object in the .yardopts file. That is my best guess as to the original intent.
2. Over time, explicitly document the entire API for this gem using YARD
3. Eventually reconsider what is returned for each method like Git::Base#commit

A friendly reminder that this issue had no activity for 60 days.

Per the last comment, .yardopts has been configured not to document a return value when a @return directive has not been given for a method. Instead of ::Object, I have configured .yardopts to consider undocumented return values to be void which means that YARD should not show the return type in the documentation.