On May 17, 2014, at 7:57 PM, Jack Bates <6ny...@nottheoilrig.com> wrote:
> Good point, > I'll look into whether those strings can be translated somehow. I looked at this patch more today, and while I think it's a nice piece of work, I question whether we should be splitting our API documentation across RST and Doxygen. RST is disappointingly opaque in many respects, but it's only one set of tools. Adding Doxygen to the mix increases the difficulty of writing documentation IMHO. It's not clear on the face of it whether APIs should be documented in RST, Doxygen, or some combination of the two. So, for now, my inclination is to not merge this. I'm happy to continue to discuss it, however, and I'm very interested in other documentation changes where the cost/benefit is more clear cut :) > On 17/05/14 07:17 AM, Masakazu Kitajo wrote: >> Extracting strings from sources would be nice, however, it makes me sad >> because API reference pages will be untranslatable. But it's much better >> than nothing or not maintained. So, that's fine with me. >> >> Personally, and as for API references, I don't build my own HTML docs >> because I can't google/yahoo them. If documents (not only ATS) are not >> online or not maintained, I'll download source codes and 'grep' them rather >> than build docs with complicated process. >> >> >> Masakazu >> >> >> >> On Sat, May 17, 2014 at 6:23 AM, Leif Hedstrom <zw...@apache.org> wrote: >> >>> >>> On May 16, 2014, at 2:18 PM, James Peach <jpe...@apache.org> wrote: >>> >>>> Does anyone have any concerns about bringing in doxygen as a >>> documentation build dependency? >>> >>> As long as it’s optional, that seems fine. I doubt many (any?) people >>> build the docs, in fact, I still think we should stop building some of our >>> docs by default, and/or fix the broken dependencies :). man pages would be >>> an exception, package builds needs to build those, but I doubt that many >>> people would build their own HTML docs vs just going to >>> http://docs.trafficserver.apache.org/. >>> >>> My $.01, >>> >>> — Leif >>> >>> >>
