You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@juneau.apache.org by GitBox <gi...@apache.org> on 2018/11/20 13:36:14 UTC
[GitHub] jamesbognar commented on issue #18: Add new vars to svl example
jamesbognar commented on issue #18: Add new vars to svl example
URL: https://github.com/apache/juneau/pull/18#issuecomment-440275613
We don't currently generate the javadocs for the examples. But should we? It probably wouldn't hurt to include them.
If we generate the javadocs, you can link to topics using a {@doc} tag so that you don't need to keep changing the version in the URL:
{@doc juneau-svl}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services
Re: [GitHub] jamesbognar commented on issue #18: Add new vars to svl example
Posted by James Bognar <ja...@gmail.com>.
HI Shalitha,
I'll add the example classes to the javadocs then.
We actually do have a section in the overview for describing examples:
http://juneau.apache.org/site/apidocs-7.2.2/overview-summary.html#juneau-examples-core
There's nothing really written yet for the core examples like there is
for the rest examples. This could be a place for
persisting/writing/saving the contents for external articles.
On Sat, Nov 24, 2018 at 2:31 AM Shalitha Suranga
<sh...@gmail.com> wrote:
>
> Hi.. James
>
> Agree with your idea. It will be great to add examples to docs. you mean better to add examples
> to another section inside overview.html?
>
>
> On Wed, Nov 21, 2018 at 6:34 AM James Bognar <ja...@apache.org> wrote:
>>
>> As I'm thinking about it more, I think adding the examples to the generated javadocs is a good idea.
>>
>> Reasons:
>>
>> Allows you to add {@doc} tags in the example javadoc comments.
>> Allows you to link to examples in overview.html.
>> Allows you to identify if documentation of examples is out-of-date with javadoc warnings.
>> Our javadocs are generated with the linksource tab so you'll be able to see the source code of the examples from the javadocs themselves.
>> (e.g. http://juneau.apache.org/site/apidocs-8.0.0/src-html/org/apache/juneau/json/JsonSerializer.html)
>>
>> Thoughts from the team?
>>
>> On Tue, Nov 20, 2018 at 11:52 PM Shalitha Suranga <sh...@gmail.com> wrote:
>>>
>>> Hi.. James
>>>
>>> Putting {@doc juneau-svl} is nice . But where we can include converted javadocs for examples?
>>> For now can we simply replace link with {@doc juneau-svl}
>>>
>>> your idea?
>>>
>>>
>>> On Tue, Nov 20, 2018 at 7:06 PM GitBox <gi...@apache.org> wrote:
>>>>
>>>> jamesbognar commented on issue #18: Add new vars to svl example
>>>> URL: https://github.com/apache/juneau/pull/18#issuecomment-440275613
>>>>
>>>>
>>>> We don't currently generate the javadocs for the examples. But should we? It probably wouldn't hurt to include them.
>>>>
>>>> If we generate the javadocs, you can link to topics using a {@doc} tag so that you don't need to keep changing the version in the URL:
>>>> {@doc juneau-svl}
>>>>
>>>> ----------------------------------------------------------------
>>>> This is an automated message from the Apache Git Service.
>>>> To respond to the message, please log on GitHub and use the
>>>> URL above to go to the specific comment.
>>>>
>>>> For queries about this service, please contact Infrastructure at:
>>>> users@infra.apache.org
>>>>
>>>>
>>>> With regards,
>>>> Apache Git Services
>>>
>>>
>>>
>>> --
>>> Regards,
>>> Shalitha Suranga
>>> shalithasuranga.github.io
>
>
>
> --
> Regards,
> Shalitha Suranga
> shalithasuranga.github.io
Re: [GitHub] jamesbognar commented on issue #18: Add new vars to svl example
Posted by Shalitha Suranga <sh...@gmail.com>.
Hi.. James
Agree with your idea. It will be great to add examples to docs. you mean
better to add examples
to another section inside overview.html?
On Wed, Nov 21, 2018 at 6:34 AM James Bognar <ja...@apache.org> wrote:
> As I'm thinking about it more, I think adding the examples to the
> generated javadocs is a good idea.
>
> Reasons:
>
> - Allows you to add {@doc} tags in the example javadoc comments.
> - Allows you to link to examples in overview.html.
> - Allows you to identify if documentation of examples is out-of-date
> with javadoc warnings.
> - Our javadocs are generated with the linksource tab so you'll be able
> to see the source code of the examples from the javadocs themselves.
> (e.g.
> http://juneau.apache.org/site/apidocs-8.0.0/src-html/org/apache/juneau/json/JsonSerializer.html
> )
>
> Thoughts from the team?
>
> On Tue, Nov 20, 2018 at 11:52 PM Shalitha Suranga <
> shalithasuranga@gmail.com> wrote:
>
>> Hi.. James
>>
>> Putting {@doc juneau-svl} is nice . But where we can include converted
>> javadocs for examples?
>> For now can we simply replace link with {@doc juneau-svl}
>>
>> your idea?
>>
>>
>> On Tue, Nov 20, 2018 at 7:06 PM GitBox <gi...@apache.org> wrote:
>>
>>> jamesbognar commented on issue #18: Add new vars to svl example
>>> URL: https://github.com/apache/juneau/pull/18#issuecomment-440275613
>>>
>>>
>>> We don't currently generate the javadocs for the examples. But
>>> should we? It probably wouldn't hurt to include them.
>>>
>>> If we generate the javadocs, you can link to topics using a {@doc}
>>> tag so that you don't need to keep changing the version in the URL:
>>> {@doc juneau-svl}
>>>
>>> ----------------------------------------------------------------
>>> This is an automated message from the Apache Git Service.
>>> To respond to the message, please log on GitHub and use the
>>> URL above to go to the specific comment.
>>>
>>> For queries about this service, please contact Infrastructure at:
>>> users@infra.apache.org
>>>
>>>
>>> With regards,
>>> Apache Git Services
>>>
>>
>>
>> --
>> Regards,
>> *Shalitha Suranga*
>> shalithasuranga.github.io
>>
>
--
Regards,
*Shalitha Suranga*
shalithasuranga.github.io
Re: [GitHub] jamesbognar commented on issue #18: Add new vars to svl example
Posted by James Bognar <ja...@apache.org>.
As I'm thinking about it more, I think adding the examples to the generated
javadocs is a good idea.
Reasons:
- Allows you to add {@doc} tags in the example javadoc comments.
- Allows you to link to examples in overview.html.
- Allows you to identify if documentation of examples is out-of-date
with javadoc warnings.
- Our javadocs are generated with the linksource tab so you'll be able
to see the source code of the examples from the javadocs themselves.
(e.g.
http://juneau.apache.org/site/apidocs-8.0.0/src-html/org/apache/juneau/json/JsonSerializer.html
)
Thoughts from the team?
On Tue, Nov 20, 2018 at 11:52 PM Shalitha Suranga <sh...@gmail.com>
wrote:
> Hi.. James
>
> Putting {@doc juneau-svl} is nice . But where we can include converted
> javadocs for examples?
> For now can we simply replace link with {@doc juneau-svl}
>
> your idea?
>
>
> On Tue, Nov 20, 2018 at 7:06 PM GitBox <gi...@apache.org> wrote:
>
>> jamesbognar commented on issue #18: Add new vars to svl example
>> URL: https://github.com/apache/juneau/pull/18#issuecomment-440275613
>>
>>
>> We don't currently generate the javadocs for the examples. But should
>> we? It probably wouldn't hurt to include them.
>>
>> If we generate the javadocs, you can link to topics using a {@doc} tag
>> so that you don't need to keep changing the version in the URL:
>> {@doc juneau-svl}
>>
>> ----------------------------------------------------------------
>> This is an automated message from the Apache Git Service.
>> To respond to the message, please log on GitHub and use the
>> URL above to go to the specific comment.
>>
>> For queries about this service, please contact Infrastructure at:
>> users@infra.apache.org
>>
>>
>> With regards,
>> Apache Git Services
>>
>
>
> --
> Regards,
> *Shalitha Suranga*
> shalithasuranga.github.io
>
Re: [GitHub] jamesbognar commented on issue #18: Add new vars to svl example
Posted by Shalitha Suranga <sh...@gmail.com>.
Hi.. James
Putting {@doc juneau-svl} is nice . But where we can include converted
javadocs for examples?
For now can we simply replace link with {@doc juneau-svl}
your idea?
On Tue, Nov 20, 2018 at 7:06 PM GitBox <gi...@apache.org> wrote:
> jamesbognar commented on issue #18: Add new vars to svl example
> URL: https://github.com/apache/juneau/pull/18#issuecomment-440275613
>
>
> We don't currently generate the javadocs for the examples. But should
> we? It probably wouldn't hurt to include them.
>
> If we generate the javadocs, you can link to topics using a {@doc} tag
> so that you don't need to keep changing the version in the URL:
> {@doc juneau-svl}
>
> ----------------------------------------------------------------
> This is an automated message from the Apache Git Service.
> To respond to the message, please log on GitHub and use the
> URL above to go to the specific comment.
>
> For queries about this service, please contact Infrastructure at:
> users@infra.apache.org
>
>
> With regards,
> Apache Git Services
>
--
Regards,
*Shalitha Suranga*
shalithasuranga.github.io