Re: Javadoc formatting style
Or (c) /** * This is the first paragraph. * * pAnd this is the second./p */ and (d) /** * This is the first paragraph.br * br * And this is the second. */ I tend to use the (c) style, because most of the time the documentation consists in only one paragraph and I don't like to overload the doc with p/p. Emmanuel Bourg Simon Kitching wrote: Hi All, I have seen two basic approaches to applying formatting to javadoc text in source files: (a) XHTML-style /** *pThis is the first paragraph./p * *pAnd this is the second./p */ (b) HTML-style /** * This is the first paragraph. * p * And this is the second. */ I would certainly like to pick one or the other for Digester2. What conventions have other commons projects adopted? Are there any good reasons to pick one over the other? Thanks, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Javadoc formatting style
Hi All, I have seen two basic approaches to applying formatting to javadoc text in source files: (a) XHTML-style /** *pThis is the first paragraph./p * *pAnd this is the second./p */ (b) HTML-style /** * This is the first paragraph. * p * And this is the second. */ I would certainly like to pick one or the other for Digester2. What conventions have other commons projects adopted? Are there any good reasons to pick one over the other? Thanks, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
[lang] uses the first. [collections] uses the second. I prefer the second as IMHO it is more readable when you are browsing the source code. And I definitely read the javadoc in source code form more than I read it in html form. Stephen - Original Message - From: Simon Kitching [EMAIL PROTECTED] I have seen two basic approaches to applying formatting to javadoc text in source files: (a) XHTML-style /** *pThis is the first paragraph./p * *pAnd this is the second./p */ (b) HTML-style /** * This is the first paragraph. * p * And this is the second. */ I would certainly like to pick one or the other for Digester2. What conventions have other commons projects adopted? Are there any good reasons to pick one over the other? Thanks, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
However, the point of javadoc is to put it in HTML, and using the latest version of HTML (ie XHTML) seems like the thing to do. Otherwise we could just ignore the p's all together and make it look even better for source reading. +1 to the first :) Hen On Mon, 7 Feb 2005 00:03:15 -, Stephen Colebourne [EMAIL PROTECTED] wrote: [lang] uses the first. [collections] uses the second. I prefer the second as IMHO it is more readable when you are browsing the source code. And I definitely read the javadoc in source code form more than I read it in html form. Stephen - Original Message - From: Simon Kitching [EMAIL PROTECTED] I have seen two basic approaches to applying formatting to javadoc text in source files: (a) XHTML-style /** *pThis is the first paragraph./p * *pAnd this is the second./p */ (b) HTML-style /** * This is the first paragraph. * p * And this is the second. */ I would certainly like to pick one or the other for Digester2. What conventions have other commons projects adopted? Are there any good reasons to pick one over the other? Thanks, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
On Sun, 6 Feb 2005 19:46:30 -0500, Henri Yandell [EMAIL PROTECTED] wrote: However, the point of javadoc is to put it in HTML, and using the latest version of HTML (ie XHTML) seems like the thing to do. Otherwise we could just ignore the p's all together and make it look even better for source reading. +1 to the first :) I am also +1 on the first (XHTML) option. -- Martin Cooper Hen On Mon, 7 Feb 2005 00:03:15 -, Stephen Colebourne [EMAIL PROTECTED] wrote: [lang] uses the first. [collections] uses the second. I prefer the second as IMHO it is more readable when you are browsing the source code. And I definitely read the javadoc in source code form more than I read it in html form. Stephen - Original Message - From: Simon Kitching [EMAIL PROTECTED] I have seen two basic approaches to applying formatting to javadoc text in source files: (a) XHTML-style /** *pThis is the first paragraph./p * *pAnd this is the second./p */ (b) HTML-style /** * This is the first paragraph. * p * And this is the second. */ I would certainly like to pick one or the other for Digester2. What conventions have other commons projects adopted? Are there any good reasons to pick one over the other? Thanks, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
On Sun, 2005-02-06 at 17:18 -0800, Craig McClanahan wrote: As should be evident from my own recent practice :-), I'm also +1 on the first (XHTML) approach. Can I ask those supporters of the XHTML style why they prefer it? Personally I think it: * increases the text size of the source file * is harder to write manually (and harder to write correctly) * makes the docs in the source file harder to read * might be easier for the javadoc app to parse, but that makes no difference to us users of javadoc; the javadoc tool support for HTML-style isn't going away. and * has no effect whatsoever on the generated html pages Not that it's a *huge* deal, but HTML-style just seems a bit better all around. Yet quite a few people obviously do prefer XHTML-style. Is it just for the purity? Regards, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
The standard HTML format is *not* the only output format you can get with Javadocs -- it is quite feasible to render alternative XML-based formats that can then be transformed using standard XML technologies -- but that only works if the markup created by Javadocs comments is well formed. In addition, the lack of rigor that HTML requires has always been my least favorite thing about the web in general -- I wish we'd started with a culture that requires well formed XML in the first place. Not having done so has had a *direct* impact on the portability of documents across browsers, and that impact has been negative overall. The same mistake has essentially been made with RSS -- instead of being disciplined about what they produce, RSS providers have expected the newsfeed readers to go through incredible contortions to read invalid feeds. That philosophy is backwards. I prefer to set a good example on things like this, rather than contributing to the problem. Craig On Mon, 07 Feb 2005 15:06:49 +1300, Simon Kitching [EMAIL PROTECTED] wrote: On Sun, 2005-02-06 at 17:18 -0800, Craig McClanahan wrote: As should be evident from my own recent practice :-), I'm also +1 on the first (XHTML) approach. Can I ask those supporters of the XHTML style why they prefer it? Personally I think it: * increases the text size of the source file * is harder to write manually (and harder to write correctly) * makes the docs in the source file harder to read * might be easier for the javadoc app to parse, but that makes no difference to us users of javadoc; the javadoc tool support for HTML-style isn't going away. and * has no effect whatsoever on the generated html pages Not that it's a *huge* deal, but HTML-style just seems a bit better all around. Yet quite a few people obviously do prefer XHTML-style. Is it just for the purity? Regards, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
My reason is quite a lot simpler than Craig's. I think of p as a container tag and not a separator tag, so I never even think of the other way of doing it. I guess we could do: /** * first * p/ * second */ and still be XML compliant (assuming an automatic root of some kind), but it would seem just as wrong to me. Hen On Sun, 6 Feb 2005 18:22:42 -0800, Craig McClanahan [EMAIL PROTECTED] wrote: The standard HTML format is *not* the only output format you can get with Javadocs -- it is quite feasible to render alternative XML-based formats that can then be transformed using standard XML technologies -- but that only works if the markup created by Javadocs comments is well formed. In addition, the lack of rigor that HTML requires has always been my least favorite thing about the web in general -- I wish we'd started with a culture that requires well formed XML in the first place. Not having done so has had a *direct* impact on the portability of documents across browsers, and that impact has been negative overall. The same mistake has essentially been made with RSS -- instead of being disciplined about what they produce, RSS providers have expected the newsfeed readers to go through incredible contortions to read invalid feeds. That philosophy is backwards. I prefer to set a good example on things like this, rather than contributing to the problem. Craig On Mon, 07 Feb 2005 15:06:49 +1300, Simon Kitching [EMAIL PROTECTED] wrote: On Sun, 2005-02-06 at 17:18 -0800, Craig McClanahan wrote: As should be evident from my own recent practice :-), I'm also +1 on the first (XHTML) approach. Can I ask those supporters of the XHTML style why they prefer it? Personally I think it: * increases the text size of the source file * is harder to write manually (and harder to write correctly) * makes the docs in the source file harder to read * might be easier for the javadoc app to parse, but that makes no difference to us users of javadoc; the javadoc tool support for HTML-style isn't going away. and * has no effect whatsoever on the generated html pages Not that it's a *huge* deal, but HTML-style just seems a bit better all around. Yet quite a few people obviously do prefer XHTML-style. Is it just for the purity? Regards, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
On Sun, 6 Feb 2005 21:45:08 -0500, Henri Yandell [EMAIL PROTECTED] wrote: My reason is quite a lot simpler than Craig's. I think of p as a container tag and not a separator tag, so I never even think of the other way of doing it. I guess we could do: /** * first * p/ * second */ and still be XML compliant (assuming an automatic root of some kind), but it would seem just as wrong to me. It would be valid only if the element that the Javadoc doclet happens to place around your Javadoc comments accepts mixed content, *AND* if the nested content is itself well formed. Java developers who count on that are, IMHO, making a mistake. Of course, I feel the same way about developers creating static HTML pages that create non-well-formed markup :-). Craig - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Javadoc formatting style
On Sun, 2005-02-06 at 18:59 -0800, Craig McClanahan wrote: On Sun, 6 Feb 2005 21:45:08 -0500, Henri Yandell [EMAIL PROTECTED] wrote: My reason is quite a lot simpler than Craig's. I think of p as a container tag and not a separator tag, so I never even think of the other way of doing it. I guess we could do: /** * first * p/ * second */ and still be XML compliant (assuming an automatic root of some kind), but it would seem just as wrong to me. It would be valid only if the element that the Javadoc doclet happens to place around your Javadoc comments accepts mixed content, *AND* if the nested content is itself well formed. Java developers who count on that are, IMHO, making a mistake. I was under the impression that doclet plugins to javadoc are always fed properly structured data, in the same way that the Necko html-parsing library presents its input data to its users as if it were well-formed xml, and therefore don't need to worry about whether the original javadoc text was HTML or XHTML style. Is this not the case? If doclets are exposed to the raw javadoc text then I would definitely agree XHTML is the way to go... Of course, I feel the same way about developers creating static HTML pages that create non-well-formed markup :-). For HTML I agree; XHTML is the way to go. But isn't javadoc is a bit different? In particular, it is read much more frequently in its raw form, and always written by hand. And it is also expected to be accessed via the javadoc doclet api rather than read directly(?). Regards, Simon - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
