Timeline for Java code documentation in a separate docs file somehow mapped to a source file?
Current License: CC BY-SA 3.0
18 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Jun 22, 2015 at 7:38 | comment | added | h.j.k. | Possibly related: how to fold/collapse comment blocks in your IDE, such as Eclipse. | |
| Jun 22, 2015 at 7:18 | history | edited | gnat | CC BY-SA 3.0 | title changed to better fit question text |
| Jun 8, 2015 at 20:46 | history | tweeted | twitter.com/#!/StackProgrammer/status/608012134384025600 | ||
| Oct 30, 2012 at 9:07 | comment | added | S.D. | @kevincline Small sections are OK, but huge ones throw me off focus when I'm scrolling through the code. By huge ones I mean when I have to include a detailed paragraph, and a mini example. | |
| Oct 29, 2012 at 17:02 | comment | added | gnat | @kevincline comments sections may indeed be overwhelming, even when filled with really useful details. See for example java.util.concurrent.Executor source code in openjdk 6-b14 | |
| Oct 29, 2012 at 15:40 | comment | added | kevin cline | @wingman: Still curious about your objection. Do you dislike comment sections in general, or the useless comments that litter so many projects. | |
| Oct 29, 2012 at 14:51 | vote | accept | S.D. | ||
| Oct 29, 2012 at 14:47 | answer | added | gnat | timeline score: 8 | |
| Oct 29, 2012 at 14:06 | history | edited | gnat | CC BY-SA 3.0 | clarification copied into question from comments |
| Oct 29, 2012 at 13:54 | comment | added | S.D. | @unholysampler Thanks. So, its generally not a good Idea. I'just have never (personally) liked huge comment sections littered in code , so was just looking for options. You might like to transfer your comment to an answer. | |
| Oct 29, 2012 at 13:38 | comment | added | unholysampler | The real problem with documenting code in a different file is that it is less likely to get updated. When a function changes, sometimes the documentation is not always updated to exactly match it. If the documentation is moved to a different file, there is now one extra step to making the correct change. It also make it less obvious that the documentation is wrong. You will only see it when you look specifically at the documentation, not when you scroll passed it in the code. | |
| Oct 29, 2012 at 13:30 | comment | added | gnat | it would be great if your question explained what kind of problems you're having with standard javadoc. As currently phrased, it's hard to tell whether there is a problem at all, making attempts to answer the question kind of a guessing game | |
| Oct 29, 2012 at 13:23 | comment | added | S.D. | Kindly enlighten me about what in this question makes it impractical, unreal. I'll appreciate that too. | |
| Oct 29, 2012 at 13:15 | comment | added | gnat | "You should only ask practical, answerable questions based on actual problems that you face." (faq) | |
| Oct 29, 2012 at 13:12 | comment | added | S.D. | @downvotes looks like I've irritated the religious coders :) | |
| Oct 29, 2012 at 13:08 | comment | added | S.D. | @gnat just personal preference, for a hobby project. | |
| Oct 29, 2012 at 13:05 | comment | added | gnat | why would you need this? | |
| Oct 29, 2012 at 13:03 | history | asked | S.D. | CC BY-SA 3.0 |