GroovyDoc, Groovy -n, Doxygen Code blocks

Table of Contents

• GroovyDoc
  • Could I combine Doxygen with GroovyDoc?
• Groovy -n
• Doxygen Code blocks
• Interesting web pages
  • javadoc
  • GroovyDoc
  • Logging
  • Java Folder Structure

Saturday 24^th June, 2017

GroovyDoc

I'd like to use Doxygen for my Groovy code, but it's not Groovy aware. The Groovy install includes GroovyDoc, which is a Groovy aware clone of JavaDoc. But JavaDoc and GroovyDoc seem very basic when compared to Doxygen.

GroovyDoc does not use markdown, but does allow HTML. I could translate my existing markdown comments into HTML, but it's not a nice way to work.

Could I combine Doxygen with GroovyDoc?

My large comment blocks, mainly in file / class headers, could be moved into a Doxygen project. This would be the product, design and user documentation.

GroovyDoc would document the implementation details.

But how do I link the two projects together? If I can generate Doxygen style tag files from the GroovyDoc output that would get me half-way there. Ideally I'd like an easy way to link back from GroovyDoc to Doxygen as well, without using hand-crafted HTML anchor tags.

The generated GroovyDoc HTML looks pretty clean. Building a tag file from it shouldn't be too hard. I'll only implement that if / when I need to.

Groovy -n

Groovy's -n command line option is used to read a file line by line. I wrongly assumed that -n implied -e.

e.g. I tried this:

E:\>dir/b *.groovy | groovy -n "println ""${line}"" "

This fails with a "file not found" exception, as it thinks everything after the -n is the path to a Groovy source file.

The correct command will use both -n and e, like this:

E:\>dir/b *.groovy | groovy -n -e "println ""class ${line-'.groovy'}"" "
class Opml2Dot
class config
class JournalProject
class ProjectConfigFile
E:\>

Doxygen Code blocks

When a code block is in a language that Doxygen doesn't recognise, or regards as text, \ characters are treated as the start of an escape sequence.

Interesting web pages

javadoc

• How to Write Doc Comments for the Javadoc Tool – Oracle Java SE Documentation.
• javadoc - The Java API Documentation Generator Oracle Java SE Documentation.

GroovyDoc

• Groovy Introduces Groovydoc! – Javalobby, 26 ^th October, 2007.
• Documenting Groovy with Groovydoc – Dustin Marx, JavaWorld
• Gradle's GroovyDoc API Doumentation – Gradle documentation.
• Customise Groovydoc Output With Gradle – Hubert Klein Ikkink, mrhaki Groovy Goodness blog post, January 28^th, 2016

Logging

• Groovy Goodness: Customise Log AST Annotations – Hubert Klein Ikkink, mrhaki blog post, June 23^rd, 2016

Java Folder Structure

• Maven Introduction to the Standard Directory Layout
• Managing Source and Class Files, Oracle Java Documentation
• Best practice for project directory structure in java, CodeRanch
• Managing the Java classpath (Windows), IBM developerWorks.

---

Top of page Recent Posts The Archives   © 2017 Terry Ebdon.

Find me coding on GitHub, networking on LinkedIn, answering questions on Stack Exchange and hanging out on twitter.