Since we are talking about help stuff, (in another thread)

Do we have any tool to convert documentation written in javadoc style (those comments in the source code) to fpdoc xml? I like to write my documentation as comments...

thanks

I don't know of anything of the FPC community, but at work we extended PasDoc ( http://pasdoc.sipsolutions.net/ ) to write fpdoc compatible XML files which was rather easy to do as the already is a XML output available. I haven't published this extension though as it was only used internally and now we've completly switched to PasDoc.

Regards,
Sven

I've been working on PasDoc for a while (PasDoc2), and ended up in adding documentation in external files. But inline documentation makes sense in the implementation section, which is not handled by PasDoc.

AFAIR Lazarus already extracts and shows comments as hints, so it should be possible to e.g. extend makeskel accordingly. But updating existing documentation is not easy, like any mix of doc sources. That's why I added an visual updater to the PasDoc2 GUI, that allowed to view source and documentation in sync, jump to the next un/documented identifier, view inherited documentation etc.

DoDi

There is no such a tool.

The entire purpose of fpdoc is not to have the documentation clutter up the sources.

Michael.

Hans-Peter Diettrich wrote

I've been working on PasDoc for a while (PasDoc2), and ended up in adding documentation in external files. But inline documentation makes sense in the implementation section, which is not handled by PasDoc.

The tiOPF had all its documentation as comments inside the source code. That is the quickest way to obfuscate your source code - especially if you have descent documentation (consisting of 5 or more lines of text) for each class, method, function etc. That made the source code very hard to read.

tiOPF now moved to using fpdoc instead - documentation living outside the source code. Then registering that help with the IDE (using INF, CHM or HTML), gives you offline context sensitive help, so it is still very easy to find help on any subject - and the source code stays readable by humans.

Michael Van Canneyt wrote

The entire purpose of fpdoc is not to have the documentation clutter up the sources.

Especially true if you start adding images or diagrams (graphs, UML, screenshots etc) inside your documentation too.

Documentation belongs outside the source code, but still easily accessible.

As several different help formats are used and can be created from the help sources (is that LateX plus source-core comments ?). I think for compatibility, any additional converter from another format should target a format that can be used as source for the help file constructing make system.

-Michael

In our previous episode, Michael Schnell said:

No, it is more wiki like tags in an XML format. But that is out of source docs, what is currently most prefered by the documentation author. (and I like it more to)

In theory, you could write something that parses the comments and writes it out as XML, and then fpdoc to generate the docs. Or one could use pasdoc.

But I think it is really bad to have many different tools in the same project, that doesn�t make sense.

: I think for

compatibility, any additional converter from another format should target a format that can be used as source for the help file constructing make system.

In a perfect world maybe. But in reality the documentation content is connected with the language and the output formats. Such converters would only yield the lowest common denomitor of formatting.

Marco van de Voort wrote

No, it is more wiki like tags in an XML format. But that is out of source docs, what is currently most prefered by the documentation author. (and I like it more to)

Are you aware of NaturalDocs (www.naturaldocs.org)?

I use it because it doesn't clutter up the source code with unreadable javadoc tags. The comments are naturally formatted. They seem to be just normal comments if you are not aware that NaturalDocs is being used.

I think the current version is written in some scripting language that can easily be modified to provide different output from the current html.

Unfortunately it doesn't 'know' pascal as good as pasdoc does, but the clear syntax makes up for it.

In our previous episode, Wimpie Nortje said:

Yes, I looked at it, but IMHO while it is probably less work, creating quality docs in it (more than mere annotations) is IMHO harder.

I think the current version is written in some scripting language that can easily be modified to provide different output from the current html.

The trouble with that philosophy is that then the burden of keeping the doc system running falls on one or two persons that are fluent in the scripting language.

Unfortunately it doesn't 'know' pascal as good as pasdoc does, but the clear syntax makes up for it.

IMHO we don�t need to change at all, and fpdoc is already better than the other two.

2011/7/17 Sven Barth :

I wanted to implement output to fpdoc XML from pasdoc some time ago too (http://pasdoc.sipsolutions.net/MichalisKamburelis#Fpdoc_output). This would allow one to write comments inside sources, and generate final documentation by fpdoc. This isn't really difficult, but there's always not enough time...

For the proponents of "docs should be outside sources", it should be noted that in pasdoc, you can also put docs in separate files, by using http://pasdoc.sipsolutions.net/ReadDescriptionFromFile . But, admittedly, this does look ugly compared to nice fpdoc XML format.

As for whether it's better to put comments in sources or in separate files, I really think this is a matter of preference... Sure, docs make the unit interface much larger, but they also make it more useful. And they encourage to update docs immediately together with updating the API. The generated docs always contain a concise summary of identifiers, if one wants it. I wrote some more comments about this on http://pasdoc.sipsolutions.net/MichalisKamburelis#Should_documentation_be_placed_inside_units_interface.2C_or_in_separate_files_.3F .

In short, I like having the both options --- fpdoc is best for docs in separate files, pasdoc is best for docs inside source files. And pasdoc is maintained (although not as actively as I'd like, volunteers are welcome :)

Michalis