You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by jablko <gi...@git.apache.org> on 2014/05/13 21:22:33 UTC
[GitHub] trafficserver pull request: docs: Add Doxygen group commands to AP...
GitHub user jablko opened a pull request:
https://github.com/apache/trafficserver/pull/85
docs: Add Doxygen group commands to API sections
Where API reference pages match API sections, use the Doxygen group to include the members' signatures.
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/jablko/trafficserver docs
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/trafficserver/pull/85.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #85
----
commit 27d758224cdea1f7cb0b64fac3b313a387ccfd42
Author: Jack Bates <ja...@nottheoilrig.com>
Date: 2014-05-13T16:51:53Z
TS-2803: Use documentation strings extracted from source files in project documentation
commit e507c51cace6c73c5fc0e460b3729d2752ae8705
Author: Jack Bates <ja...@nottheoilrig.com>
Date: 2014-05-13T19:06:53Z
docs: Add Doxygen group commands to API sections. Where API reference pages match API sections, use the Doxygen group to include the members' signatures.
----
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] trafficserver pull request: docs: Add Doxygen group commands to AP...
Posted by bryancall <gi...@git.apache.org>.
Github user bryancall commented on the pull request:
https://github.com/apache/trafficserver/pull/85#issuecomment-112869333
This is the Jira ticket for it
https://issues.apache.org/jira/browse/TS-2803
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] trafficserver pull request: docs: Add Doxygen group commands to AP...
Posted by PSUdaemon <gi...@git.apache.org>.
Github user PSUdaemon commented on the pull request:
https://github.com/apache/trafficserver/pull/85#issuecomment-112869469
This is associated with JIRA TS-2803 which was closed as "won't fix". Can this be closed now, or is there something here we need to reconsider?
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
[GitHub] trafficserver pull request: docs: Add Doxygen group commands to AP...
Posted by Humbedooh <gi...@git.apache.org>.
Github user Humbedooh closed the pull request at:
https://github.com/apache/trafficserver/pull/85
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---
Re: [GitHub] trafficserver pull request: docs: Add Doxygen group
commands to AP...
Posted by James Peach <jp...@apache.org>.
On May 17, 2014, at 7:57 PM, Jack Bates <6n...@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 <jp...@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
>>>
>>>
>>
Re: [GitHub] trafficserver pull request: docs: Add Doxygen group
commands to AP...
Posted by Jack Bates <6n...@nottheoilrig.com>.
Good point,
I'll look into whether those strings can be translated somehow.
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 <jp...@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
>>
>>
>
Re: [GitHub] trafficserver pull request: docs: Add Doxygen group
commands to AP...
Posted by Masakazu Kitajo <m4...@gmail.com>.
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 <jp...@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
>
>
Re: [GitHub] trafficserver pull request: docs: Add Doxygen group commands to AP...
Posted by Leif Hedstrom <zw...@apache.org>.
On May 16, 2014, at 2:18 PM, James Peach <jp...@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
Re: [GitHub] trafficserver pull request: docs: Add Doxygen group
commands to AP...
Posted by James Peach <jp...@apache.org>.
Does anyone have any concerns about bringing in doxygen as a documentation build dependency?
On May 13, 2014, at 12:22 PM, jablko <gi...@git.apache.org> wrote:
> GitHub user jablko opened a pull request:
>
> https://github.com/apache/trafficserver/pull/85
>
> docs: Add Doxygen group commands to API sections
>
> Where API reference pages match API sections, use the Doxygen group to include the members' signatures.
>
> You can merge this pull request into a Git repository by running:
>
> $ git pull https://github.com/jablko/trafficserver docs
>
> Alternatively you can review and apply these changes as the patch at:
>
> https://github.com/apache/trafficserver/pull/85.patch
>
> To close this pull request, make a commit to your master/trunk branch
> with (at least) the following in the commit message:
>
> This closes #85
>
> ----
> commit 27d758224cdea1f7cb0b64fac3b313a387ccfd42
> Author: Jack Bates <ja...@nottheoilrig.com>
> Date: 2014-05-13T16:51:53Z
>
> TS-2803: Use documentation strings extracted from source files in project documentation
>
> commit e507c51cace6c73c5fc0e460b3729d2752ae8705
> Author: Jack Bates <ja...@nottheoilrig.com>
> Date: 2014-05-13T19:06:53Z
>
> docs: Add Doxygen group commands to API sections. Where API reference pages match API sections, use the Doxygen group to include the members' signatures.
>
> ----
>
>
> ---
> If your project is set up for it, you can reply to this email and have your
> reply appear on GitHub as well. If your project does not have this feature
> enabled and wishes so, or if the feature is enabled but not working, please
> contact infrastructure at infrastructure@apache.org or file a JIRA ticket
> with INFRA.
> ---
[GitHub] trafficserver pull request: docs: Add Doxygen group commands to AP...
Posted by zwoop <gi...@git.apache.org>.
Github user zwoop commented on the pull request:
https://github.com/apache/trafficserver/pull/85#issuecomment-56891475
Is this done/ If so, please close.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---