[fpc-pascal] Brook 1.0 - A new framework for web was born

[Michalis Kamburelis]

michael.vancanneyt at 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