On 6/24/2017 11:28 PM, Anatol Belski wrote: > I voted no, because it is too short term and I'd see a productivity > drop having such an obligation suddenly right in place for 7.2. To > implement the change, there's more than just to put the doc into the > source. Every piece of code needs to be revisited by someone who > understands it. > > I'm not saying the current situation is better than the aim, but to > be realistic - the change needs a culture to be developed. It is > clear, that some know doxygen, but I believe maintaining the doc will > be still a huge effort for many contributors. If some patch were in > place - at least one would have a source for learning by watching, so > it would reduce the learn hurdle 😊 Without being familiar with > Doxygen the actual productivity will for sure suffer. > > Neither there's a patch covering at least the very core, nor there's > a strategy for the transition period. I can imagine, that even if the > RFC is voted positive, many contributors not familiar with doxygen > won't have time to complete the doc part. The intention good, but the > assertion might be hard. I might be wrong, but ATM I think the > intention is good, whereby the RFC implementation owes IMHO some > elaborated strategy. > > Regards > > Anatol >
We are only voting that we want to use Doxygen for documentation as a format, not that documentation is a must for PRs or anything. From the RFC: > This RFC does not propose any big documentation fest where development > is halted and everybody starts writing documentation. Rather to start > documenting in the future, as well as while refactoring or rewriting > existing code. Hence, it would be nice to write a little while one is working on something anyways. There is no must to document! There is a must that IF you document, that it must use Doxygen. That's what we are voting on. Everybody has plenty of time to get acquainted with Doxygen and we can create follow-up RFCs with clearer rules on how to document (if need be). -- Richard "Fleshgrinder" Fussenegger
signature.asc
Description: OpenPGP digital signature
