Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
InfoSec812 opened this issue Nov 2, 2015 · 6 comments
Closed

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

InfoSec812 opened this issue Nov 2, 2015 · 6 comments
Labels

Comments

@InfoSec812
Copy link

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
Copy link
Author

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
Copy link
Owner

Abnaxos commented Nov 22, 2015

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 added a commit that referenced this issue Dec 1, 2015
This also adds a specification demonstrating that the example from issue #44 works.
@Abnaxos
Copy link
Owner

Abnaxos commented Dec 1, 2015

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.

Abnaxos added a commit that referenced this issue Dec 1, 2015
@andreashe
Copy link

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

@andreashe
Copy link

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

@Abnaxos
Copy link
Owner

Abnaxos commented Mar 30, 2016

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants