Javadoc: podziały wierszy bez tagów HTML?

81

Przepraszam za prawdopodobne pytanie typu FAQ, ale po prostu nie mogę znaleźć odpowiedzi.

O ile pamiętam Eclipse, pusty wiersz w komentarzu Javadoc jest wyświetlany (w wyskakujących okienkach Javadoc w źródle) jako podział wiersza (z dodatkowymi odstępami w pionie).

Jednak w Netbeans tak nie jest.

Czy mogę skonfigurować Javadoc, aby interpretował pusty wiersz jako podział wiersza?

Dodatkowe pytanie: czy mogę zastąpić domyślne zachowanie Netbeans (związane z tym) dla wyskakujących okienek Javadoc w źródle?

O czym mówię to:

Źródło

/**
 * Paragraph One
 *
 * Paragraph Two
 */
 void someMethod() { }

Interpretacja Eclipse

 Paragraph One

 Paragraph Two

Interpretacja Netbeans

 Paragraph One Paragraph Two
java.is.for.desktop
źródło
1
Wiele z tych odpowiedzi jest obecnie nieaktualnych (zastąpionych) przez NetBeans8.2, zobacz odpowiedź z @fujy poniżej, działa idealnie.
Webel IT Australia - upvoter

Odpowiedzi:

80

Nie ma to nic wspólnego z Netbeans. Podejrzewam, że patrzysz na kod źródłowy w jednym przypadku, a dane wyjściowe Javadoc w drugim. Nowe linie nie mają znaczenia w HTML: ergo wyjście ich nie pokaże. Jeśli chcesz wprowadzić nową linię, użyj a <p>lub a <br>.

user207421
źródło
4
Jak już wspomniano w pytaniu, Eclipse ma rozważyć puste wiersze jako ust. Dlatego zakładam, że musi to być możliwe do osiągnięcia przez jakąś konfigurację javadoc (Netbeans lub bez).
java.is.for.desktop
Eclipse pokazuje kod źródłowy bez względu na to, jak jest sformatowany. Netbeans 6.9.1 pokazuje również kod źródłowy, jak wyżej, tj. Nie ignoruje też znaków końca linii. Jeśli jednak patrzysz na wyjście Javadoc w jakikolwiek sposób, jeśli byłoby to niepoprawne, oznacza to, że nie należy ignorować łamania linii.
user207421
40

Nie jestem pewien, czy to pomoże w przypadku OP, jednak założyłem <pre></pre>dokument, aby netbean nie zepsuł mojego formatowania. Tak to będzie wyglądać

/**
 * <pre>
 * Paragraph One
 *
 * Paragraph Two
 * </pre>
 */

Jest to najbliższe pokazaniu nowych wierszy w formacie tekstowym. Używam NetBeans 7.1.2. W ten sposób użycie code formatopcji nie spowoduje przeformatowania dokumentu. Wyświetlanie dokumentu we wskazówkach jest nadal sformatowane.

Aktualizacja: w Netbeans 8.x istnieje opcja w formatowaniu kodu, aby wyłączyć formatowanie komentarzy.

AaA
źródło
13

Istnieje już opcja NetBeans- przetestowana w wersji 8.2 - która pozwala zachować nowe linie w komentarzach i / lub dodać <p>znacznik do swojego, Javadocjeśli to konieczne

  • Tylko z Toolsmenu, wybrałemOptions
  • Przejdź do Editorkarty, a następnie do Formattingkarty
  • W Languagemenu wybrałeś Java, aw Categorymenu wybrałeśComments
  • Zaznacz pole Preserve New Lineswyboru w Generalsekcji, jeśli chcesz zachować nowe wiersze w komentarzach. Pozwoli to zachować nowe linie bez dodawania <p>tagu
  • Zaznacz Generate "<p>" on Blank Linespole wyboru w Javadocsekcji, jeśli chcesz również dodać <p>tag .

wprowadź opis obrazu tutaj

fujy
źródło
2
Zdecydowanie najlepsza odpowiedź z NetBeans 8.2. Łatwy. Ale powinieneś go zmodyfikować, aby dodać, że faktycznie uruchamia się tylko wtedy, gdy wykonujesz formatowanie w kodzie (z istniejącymi znakami końca linii). Trzeba być ostrożnym, jeśli są już <p>tam ręcznie, czasami można dodać dwukrotnie <p>``<p>za pierwszym razem. Następnie działa zgodnie z oczekiwaniami.
Webel IT Australia - upvoter
4

Zgadzam się z tobą, HTML nie należy do kodu źródłowego. Niestety, nie znalazłem wiele pomocy w szukaniu tego w Google. W rzeczywistości jest to dość łatwe do wdrożenia.

Oto niestandardowy Doclet, który możesz skompilować i używać:

import com.sun.javadoc.*;
import com.sun.tools.doclets.standard.*;

/**
 * Formats text-only comments with HTML.
 */
@SuppressWarnings("restriction")
public final class TextDoclet {
    private static final Pattern NEWLINE_REGEX = Pattern.compile("\\n");
    private static final String BR = "<br/>\n";

    public static boolean start(RootDoc rootDoc) {
        for ( ClassDoc classdoc : rootDoc.classes())
            classdoc.setRawCommentText(formatText(classdoc.getRawCommentText()));

        return Standard.start(rootDoc);     
    }

    private static String formatText(String text) {
        return NEWLINE_REGEX.matcher(text).replaceAll(BR);
    }
}

Przykład wywołania go za pomocą javadoc:

javadoc -docletpath ~/project/text-doclet/target/text-doclet-1.0.0-SNAPSHOT.jar -doclet com.myorg.textdoclet.TextDoclet -sourcepath ~/project/myapp/src/main/java -subpackages com.myorg.myapp
roylaurie
źródło
2

JavaDoc wyświetla sposób, w jaki style CSS zostały zdefiniowane. Aby to zrobić, możesz edytować style CSS powiązane ze znacznikami akapitu:

p {
    line-height: 25px;
}
adarshr
źródło
1
Dziękuję, ale jestem pewien, że Netbeans w ogóle nie interpretuje pustego wiersza jako akapitu (patrz „Interpretacja Netbeans” w moim pytaniu). To znaczy: możesz zdefiniować odstępy między wierszami tylko wtedy, gdy masz linie.
java.is.for.desktop
Hmm. Widziałem to. Ale nie jestem pewien, czy Netbeans zapewnia opcję edycji tego.
adarshr
2

Jest to pseudo-rozwiązanie
(które niestety wpływa tylko na wygenerowany javadoc, ale nie wpływa na wyświetlanie javadoc w źródle Netbeans).

Określ arkusz stylów zawierający następujące elementy:

div.block {
    white-space: pre;
}
java.is.for.desktop
źródło
0

Nie mam pojęcia, co robi tutaj Eclipse, ale jeśli chcesz ogólnie tego zachowania (nie tylko IDE), być może będziesz musiał utworzyć nowy Doclet (który może być oparty na domyślnej dokumentacji HTML), zamiast tego wstawić <p>at każda pusta linia lub coś takiego.

Paŭlo Ebermann
źródło