Hey Stas! On 5/30/2017 12:50 AM, Stanislav Malyshev wrote: > Hi! > >> I used Doxygen in both PRs to document the code. Right now the code base >> is lacking a lot of documentation, which, if done right, would greatly >> improve accessibility of the code base. > > Well, the problem as I understand it is that we don't have Doxygen setup > for docs generation. So, adding docs in Doxygen format is not very > useful, until we get some Doxygen setup. > > If we don't get one, then I think it's better to use format that is > either completely generic (no special tags, etc.) or matching existing > usage. > > Or make an RFC to establish docs standard, be it Doxygen or anything > else. Which of course would include some plan on how to deploy that system. >
Not sure if it is really so important to actually generate the doc. It is imho more important to have documentation in the first place. The problem with no format is simply that it is not easy to document things consistently. For instance input/output parameters, return values, where else to look at, examples, etc. I am documentation all of my PHP code, everywhere, but never generate any API docs for it. Just having the documentation as part of the code is sufficient in 99% of all cases. A simple [Ctrl]+[Q] or hovering with the mouse will bring it up, that's what I care about. ;) On 5/30/2017 12:50 AM, Stanislav Malyshev wrote: > But randomly introducing docs system without any explicit decision in an > unrelated patch doesn't look like a good idea to me. > Wow! This sounds like you think that I am trying to deliberately sabotaging the PHP project. Quite the opposite is the case. I am simply used to properly documenting my code, as it is part of any professional code base in my opinion. -- Richard "Fleshgrinder" Fussenegger
signature.asc
Description: OpenPGP digital signature
