| Re: [jetty-dev] Embedded Examples |
just to toot the horn of the docs some more, things I like are:- the title of the Example has a link to the actual source- you can doubleclick on the source and it makes it simple to cut and paste- <version> in maven coordinates section uses the ${project.version} trick so it is always up to date with the version of the documentation
On Thu, May 23, 2013 at 3:34 PM, Jesse McConnell <jesse.mcconnell@xxxxxxxxx> wrote:I added the following page earlier today.I wanted to get feedback on the general approach. This is largely in response to the number of times I have run across people stumped on seemingly simple embedded jetty usage and their inability to find more complete examples. I have also linked a lot of folks in stack overflow and on jetty irc directly to our embedded examples and it would be better if we could link into our docs and help people help themselves.So...what I want to do is slurp in the file like I show above and then have a walk through section that explains some of the nuts and bolts of embedded behavior in a step by step manner. Personally I like the approach of the walkthrough indicating the lines that the description pertains to but this has the potential to get out of date. However I have an <important> tag at the top and I am personally comfortable with it getting out of date and having a clear notification mechanism for addressing it like this. Also the examples do not change frequently so...Now, the flip side is that we could just document our example files better and merge the walkthrough together with the comments in the java files, but we hit a technical limitation with the JavaParser we are using to support pulling out specific methods into the documentation. The comments are basically chewed up :)so...I can spend some time sorting that out but personally I rather like the approach I have here so I wanted to get some other opinions.cheers,jesse
_______________________________________________
jetty-dev mailing list
jetty-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/jetty-dev