Pegasus documentation cannot produce valid javadoc with certain symbols

[jplaisted]

It seems like Pegasus will do some parsing of documentation tags and spit out the "parsed" strings into the javadoc. This actually makes it invalid.

Example:

  // some enum PDL
  /**
   * Represent the relation greater than, e.g. ownerCount > 5
   */
  GREATER_THAN

    // generated java
    /**
     * Represent the relation greater than, e.g. ownerCount > 5
     * 
     */
    GREATER_THAN,

[BrianPin]

@jplaisted Hi, Would you mind give me some context? from the examples, are you saying the "> 5" is invalid for you?

[jplaisted]

In the above I gave the PDL (which used >) and the javadoc it generated (which translated it to >).

> is an invalid character in javadoc.

[jplaisted]

If you're unaware, Javadoc supports HTML tags. So characters like < and > and invalid on their own and need to use HTML escaping for some things.

I suggest you don't "translate" any documentation here when generating javadoc. Just print it literally. Then PDL annotations can use javadoc syntax directly (so > in PDL becomes > in javadoc, which is valid). The other option is to transform PDL doc to javadoc; so if there is a > in the pegasus doc translate it to >).

[BrianPin]

got it, I will investigate and get back here

[BrianPin]

Well, looks like that is the intended design, in restli:

  @Test
  public void testUnescapeDocstring()
  {
    String extracted = PdlParseUtils.extractMarkdown(
        "  /**\n" +
        "   * <div>Some html</div>\n" +
        "   * /* A comment */\n" +
        "   */\n");
    assertEquals(extracted,
        "<div>Some html</div>\n" +
        "/* A comment */");
  }

The specific unescape is happening inside

StringEscapeUtils.unescapeHtml4(commentUnescaped);

I think if we change this it will affect a lot.

I would like to discuss with our staffs to gain better decision making.

[evanw555]

We agreed that the current behavior isn't ideal, but there are other concerns about how this would affect current use cases. We're tracking this internally and we'll revisit this issue later once we have bandwidth.

[BrianPin]

I created a ticket under my name! FYI