Abnaxos / markdown-doclet

A Doclet that allows the use of Markdown in JavaDoc comments.
GNU General Public License v3.0
319 stars 40 forks source link

Markdown not being processed in package-info.java files #44

Closed InfoSec812 closed 8 years ago

InfoSec812 commented 8 years ago

I have a Gradle project:

group 'us.juggl.twentyfifteen'
version '1.0-SNAPSHOT'

apply plugin: 'java'
apply plugin: 'application'

sourceCompatibility = 1.8

mainClassName = 'us.juggl.twentyfifteen.november.annotations.Main'

repositories {
    mavenCentral()
}

configurations {
    markdownDoclet
}

javadoc.options {
    docletpath = configurations.markdownDoclet.files.asType(List) // gradle should relly make this simpler
    doclet = "ch.raffael.doclets.pegdown.PegdownDoclet"
    addStringOption("parse-timeout", "10")
}

dependencies {
    compile group: 'org.projectlombok', name: 'lombok', version: '1.16.6'
    compile group: 'org.slf4j', name: 'slf4j-api', version: '1.7.12'
    testCompile group: 'junit', name: 'junit', version: '4.11'
    runtime group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl', version: '2.4.1'
    runtime group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.4.1'
    markdownDoclet group: 'ch.raffael.pegdown-doclet', name: 'pegdown-doclet', version: '1.1.1'
}

And inside of src/main/java/us/juggl/twentyfifteen/november/annotations/ I have a package-info.java file for the package level JavaDocs. Pegdown is not processing the markdown in that file, I just see raw text in the generated JavaDocs.

InfoSec812 commented 8 years ago

Update to the above... SOME markdown is being processed. The <h1> header is NOT being processed. See the following example:

/**
 * # November 2015, Java Users Group of Greater Louisville
 *
 * ## Annotations In Java
 *
 * This example code will demonstrate the use and some of the implementation of Annotations in Java.
 *
 * Person
 * :   A simple [POJO](https://en.wikipedia.org/wiki/Plain_Old_Java_Object) annotated with [Lombok](http://projectlombok.org) to demonstrate how annotations can be used.
 */

The header at the top is NOT being processed, but the definition below IS being processed.

Abnaxos commented 8 years ago

Hm … it worked fine for me. I couldn't imagine why this shouldn't work, anyway.

What about the second h2? Is this one being processed?

Abnaxos commented 8 years ago

I've added a test that demonstrates that your example works – to a certain extent. The documentation is rendered fine in the full package documentation. However, the summary doesn't look nice. It seems that Javadoc just took the whole text until the first '.' as first sentence and removed all Tags from it. The result is the following summary:

November 2015, Java Users Group of Greater LouisvilleAnnotations In JavaThis example code will demonstrate the use and some of the implementation of Annotations in Java.

Looking at the source code, the </h1> tag should have been recognised as a sentence breaker, yielding this package summary:

November 2015, Java Users Group of Greater Louisville

In this case, this doesn't make much sense as a summary IMHO, but as far as I can see, this should be the correct behaviour. I'll look deeper into this. As a workaround, precede the full documentation with a simple summary paragraph.

It looks like I'll have to fiddle with some Javadoc implementation internals here.

andreashe commented 8 years ago

For me it also does not work. Nothing interpretet. Even not your example. It keeps the raw text.

andreashe commented 8 years ago

I determined, that it works only if the package has a class! If it is empty, it does not process!

Abnaxos commented 8 years ago

@InfoSec812 This is actually documented behaviour: Option -breakiterator

Invoking with javadoc -locale en fixes the issue by forcing the internal sentence breaker which also recognises HTML tags.

If the locale is not set to 'en' (or using a locale specific sentence breaker is forced by -breakiterator), JavaDoc uses BreakIterator::getSentenceInstance(Locale). This won't recognise </h1> as the end of a sentence. This is a shortcoming of javadoc, there's nothing I can do about this.

The only workaround I see is: Use javadoc -locale en

@andreashe That's a different thing. Probably, it also has nothing to do with this doclet.