Show quoted text 20 lines
On Sun, 16 Dec 2012, Graeme Geldenhuys wrote:
> On 15/12/2012 21:22, Sven Barth wrote:
>>
>> Maybe because the authors prefered inline comments instead of fpdoc's
>> XML files...
>
> A shame, because the more detailed the documentation, the more it
> obfuscates the code.
>
> eg: Documentation Insight, a popular Delphi IDE plugin for documenting
> frameworks from inside the IDE's most requested feature... "external
> documentation files" because good documentation means lots of text and
> examples, thus lots and lots of code obfuscation.
Exactly the reason why fpdoc uses external XML.
A pasdoc-to-fpdoc conversion is on my TODO list. (tracker item 325689871
;))
(We're getting off-topic from Brook, sorry...)
A couple of answers (from the position of both PasDoc user and developer):
1. Although I personally prefer pasdoc, I was also thinking about implementing pasdoc output that produces fpdoc-compatible XML. This is quite easy to do in pasdoc (e.g. see our existing "simplexml" output), so if you want to do it this way, patches are surely welcome :) I wrote about it on http://pasdoc.sipsolutions.net/MichalisKamburelis#Fpdoc_output .
2. As for the discussion about whether it's better to have docs inside comments or as a separate files:
2.1. For what it's worth, you can place descriptions in separate files and still use PasDoc, see
http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . Whether this format is cleaner or not than fpdoc's XML file is up to the debate, anyway you *can* use separate files for the documentation. We also have features like introduction/conclusion where you write completely separate pages using pasdoc markup.
2.2. As for whether it's better to place documentation in comments or in separate files, I wrote about this on
http://pasdoc.sipsolutions.net/MichalisKamburelis#Should_documentation_be_placed_inside_units_interface.2C_or_in_separate_files_.3F . And I still believe that generally the answer is "it is a matter of taste".
It comes down to the fact that I don't mind having a large unit interface with long comments inside. I don't see this as "code obfuscation", I see my comments and examples as crucial and useful information that I want to keep together with the interface. You no longer can easily see the list of all your methods "at a glance", but you can see them in the pasdoc output, so no loss.
And the big advantage of keeping documentation inside source code is that it makes documentation easier to keep synchronized with code. Patches to the source code often naturally contain also changes to the related documentation in the interface. This keeps docs very up-to-date in my experience, which also means complete. YMMV of course, but I definitely know examples of PasDoc-produced documentation where it's very complete and useful.
With documentation in a separate file, there is a risk that you will see writing documentation as a "separate task", where you need to go edit "these other files". In such case, chances of getting contributions that update both the source *and* the relevant documentation are much lower, at least in my experience.
One practical note is also that "documentation in source code" approach is used by many tools in a lot of other languages too: Doxygen, OcamlDoc, JavaDoc, PhpDoc... Languages like Python and Lisp even recommend to place docs inside special strings in code (not just comments). So, somehow this approach can work Ok :)
Michalis
