michael.vancann...@wisa.be wrote:
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
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/mailman/listinfo/fpc-pascal
