On Thursdy, May 18, 2017, Stas Malyshev <smalys...@wikimedia.org> wrote: > Hi! > >> What are people's opinions on using it? > > I think it's OK to use it in relevant cases (along with already existing > and used @see) and recognize such uses as documented, but making it > mandatory would look like increasing busywork for a doubtful benefit of > making robots (e.g. syntax checkers) not bother us with warnings. Since > I see the purpose of robots to make _less_ busywork, this seems to be > counter-productive. > For the benefit of humans, if they're reading generated docs, doc > generators should be already able to handle inheritance? If they're > reading raw code @inheritdoc provides marginal benefit of reminding to > look into parent method, but most people probably would do it anyway if > child method does not have docs.
Sometimes its not that obvious if the class introduces new methods which are documented. In the past ive been bitten by the docs for db being in IDatabase, when i didnt think to look beyond the abstract base class. As someone who only reads docs in source, i think @inheritdoc is a useful reminder. -- bawolff _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
