Timeline for Is there any logical reason to auto-generate code documentation?
Current License: CC BY-SA 3.0
15 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Sep 11, 2014 at 19:36 | comment | added | Kyle Strand | @DavidHammen Agreed, that GhostDoc stuff looks absurd. | |
| Sep 11, 2014 at 18:35 | comment | added | David Hammen | @KyleStrand _ I stand corrected. Doxygen does not produce such nonsense. Doxygen reads but does not generate doxygen comments. Those doxygen comments need to be written by a human. | |
| Sep 11, 2014 at 17:33 | comment | added | Kyle Strand | I've updated my answer accordingly. | |
| Sep 11, 2014 at 17:33 | history | edited | Kyle Strand | CC BY-SA 3.0 | added 1881 characters in body |
| Sep 11, 2014 at 17:04 | comment | added | Kyle Strand | @DavidHammen I think I may have misunderstood the question, actually, because on re-reading, it looks to me like GhostDoc is more or less attempting to "read the programmer's mind," as you say. Check out the page with examples; the comments themselves have been generated by GhostDoc. | |
| Sep 11, 2014 at 14:34 | comment | added | David Hammen | @cdorking: As far as how to tell what was auto generated, look at this page that describes a function deep within the guts of Eigen. The calling sequence is autogenerated. Much of the text below the calling sequence is hand-written. The math is hand-written LaTeX that doxygen automatically processes. The list of parameters: The names are autogenerated, but the meaning of those parameters comes from hand-written commentary. The list of functions referenced within is autogenerated. | |
| Sep 11, 2014 at 14:29 | comment | added | David Hammen | @cdorking: You misread the question. Read it again. GhostDoc was not attempting to read the programmer's mind. That goofy phrase appeared precisely because a programmer explicitly wrote that phrase as a comment to be parsed by GhostDoc. GhostDoc doesn't know what that phrase means. Like doxygen or javadoc, GhostDoc reproduces key commentary hand-written by humans as-is (plus formatting). There is no mind reading going on. | |
| Sep 11, 2014 at 14:19 | comment | added | dcorking | @DavidHammen I was quoting the original question, which is about a tool, GhostDoc, that attempts to read the programmer's mind, and sometimes fails. How can I tell from the Eigen manual what has been written by machine? | |
| Sep 11, 2014 at 14:04 | comment | added | David Hammen | @dcorking _ I haven't the foggiest idea what you mean by that. Doxygen can't read the programmer's mind. For a good example of what doxygen can do, see this top-level page for Eigen, a rather popular C++ scientific computing package. Poke around! You can see some documentation that's obviously written by humans, other that is purely auto generated, yet other that is a blend of human-written and auto generated. If told to, doxygen will automatically generate fan-in (who references this function) and fan-out (what does this function call). | |
| Sep 11, 2014 at 12:50 | comment | added | dcorking | @DavidHammen so does Doxygen generate sentences, like "Riches the text selection changed."? (I have not used it in many years, and those early versions did not generate English that I recall.) | |
| Sep 10, 2014 at 15:09 | comment | added | David Hammen | Actually, it's both. doxygen parses the code and the doxygen comments. Class names, parent class names, data member names, function names, argument types and names, return type: Those all come from the parsed code. What those things mean come from the doxygen comments. Doxygen complains if an item specified as a \param in the doxygen comment isn't an argument, and it can be made to complain about undocumented items. Other than these minimal checks, the problem of comment vs code mismatch is still a possibility. That said, I love doxygen. It's much better than writing an API by hand. | |
| Sep 9, 2014 at 16:40 | comment | added | Kyle Strand | @dcorking The latter, although it also tries to organize everything according to the static structure of the code and provide automatic hyperlinks everywhere possible (and these are frequently wrong). | |
| Sep 9, 2014 at 13:50 | comment | added | dcorking | Does Doxygen output English, or does it merely format doc strings that are already written in English? | |
| Sep 8, 2014 at 18:08 | review | First posts | |||
| Sep 8, 2014 at 20:48 | |||||
| Sep 8, 2014 at 18:08 | history | answered | Kyle Strand | CC BY-SA 3.0 |