Vermeidung von Duplikaten in JavaDoc-Kommentaren

Ich schreibe eine Klasse, in der dasselbe XML zwischen einigen Methoden verwendet wird.Vermeidung von Duplikaten in JavaDoc-Kommentaren

z.B.

/** 
* Sample Response: 
* <xmp> 
*  <myXML> 
*   <stuff> data </stuff> 
*  </myXML> 
* </xmp> 
*/ 
CommonXML Method1(); 

/** 
* Sample Submission: 
* <xmp> 
*  <myXML> 
*   <stuff> data </stuff> 
*  </myXML> 
* </xmp> 
*/ 
void Method2(CommonXML xml);

Ich möchte meine Dokumentation schreiben, so dass, wenn die XML-Änderungen, die ich eine Ressource zu modifizieren, anstatt alle der JavaDoc für die betroffenen Methoden zu aktualisieren.

Weiß jemand, wie man das erreicht?

Quelle

2011-01-14 TERACytE

Ich denke, Sie können eine Klasse angeben, um es java-doc zu erstellen. muss aber Google. :) – Nishant

Ich denke, Variablendefinitionen in Javadoc wiederverwenden zu wollen, ist ein häufiges Problem. Die Tatsache, dass das OP hier nach einem XML-Dokument fragt, verbirgt, wie häufig es ist - siehe http://stackoverflow.com/questions/7021696/javadoc-reusable-parameter-values und http://stackoverflow.com/questions/1036565/is -it-possible-to-re-use-param-Beschreibungen-in-javadoc –

Warum Ihre Dokumentation nicht gelesen haben:

/** 
* Returns an XML file conforming to the CommonXML schema, available here 
* (link-to-schema). 
**/

Dann, wenn Sie Ihre XML aktualisieren Sie Ihr Schema aktualisieren gerade?

Quelle

2011-01-14 20:53:46 JohnnyO

Sie sollten den Satz mit einem Punkt gemäß den JavaDoc-Richtlinien beenden. –

Notiert und behoben. – JohnnyO

Wie wäre es mit @see auf die andere Methode verweisen?

Quelle

2011-01-14 20:55:07

Ich würde dokumentieren (unter Zwang - eigentlich denke ich Dokumentation ist eine Verschwendung von Zeit, wie es fast immer falsch ist - verwenden Sie Tests, um zu dokumentieren, was Ihr System) das CommonXML-Objekt, anstatt jede Methode, die ein Objekt davon Art.

Quelle

2011-01-14 20:57:12 time4tea

+1 für den Vorschlag, das CommonXML-Objekt zu dokumentieren (und fast ein -1 für Dokumentation zu denken ist eine Verschwendung von Zeit .. nichts ist frustrierender, dass Debugging-Code, der nicht dokumentiert ist .. Lesen von Tests, um herauszufinden, was der Code ist zu tun ist ist viel zeitaufwändiger .. Dokumentation ist eine erstklassige Pflicht eines Entwicklers!) –

Da 90% der Entwickler Zeit ausgegeben wird Code lesen, bevorzuge ich die "Dokumentation" Zeit Refactoring der Code, so zu verbringen das ist wirklich leicht zu verstehen. Wie auch immer, ich verstehe, dass Leute solche Dinge stark vertreten haben! – time4tea

Die Kommentare werden von den Verbrauchern verwendet, was ich produziere, also ist es keine Lösung, mit der ich arbeiten kann. – TERACytE

Sie sollten Javadoc nicht verwenden, um Spezifikationen zu wiederholen, die an anderer Stelle definiert sind. Siehe auf die Spezifikation.

Quelle

2011-01-15 00:34:31 EJP

Sie könnten dazu Doclava 's include or sample tag verwenden. Diese Tags kopieren Beispieltext aus einer beliebigen Datei in die Ausgabe javadoc html. Der Tag @include kopiert den Text wörtlich aus der angegebenen Datei. Das Tag @sample kopiert den Text aus der angegebenen Datei mit einigen Änderungen.

Quelle

2013-02-13 15:59:48

Vermeidung von Duplikaten in JavaDoc-Kommentaren

Antwort

Verwandte Themen