From 7a28c24c9140790d42b05059698246d5d3024459 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jochen=20St=C3=A4rk?= Date: Thu, 21 May 2026 09:55:06 +0200 Subject: [PATCH] Around an hour of manual javadoc documentation (why don't I just use chatGPT for that?) --- .../org/mustangproject/CalculatedInvoice.java | 21 +++++++++++++ .../java/org/mustangproject/CashDiscount.java | 11 +++++++ .../java/org/mustangproject/DirectDebit.java | 5 +++ .../java/org/mustangproject/EStandard.java | 31 ++++++++++++++++++- .../Exceptions/ArithmeticException.java | 8 ++++- .../Exceptions/ArithmetricException.java | 9 +++++- .../main/java/org/mustangproject/Invoice.java | 14 +++++++-- .../ZUGFeRD/CustomXMLProvider.java | 3 ++ .../ZUGFeRD/DAPullProvider.java | 3 ++ .../ZUGFeRD/IZUGFeRDExporter.java | 17 ++++++++++ .../ZUGFeRD/model/DateTimeTypeConstants.java | 3 ++ .../model/DocumentCodeTypeConstants.java | 10 ++++++ ...DocumentContextParameterTypeConstants.java | 9 ++++++ .../util/ByteArraySearcher.java | 15 +++++++++ 14 files changed, 153 insertions(+), 6 deletions(-) diff --git a/library/src/main/java/org/mustangproject/CalculatedInvoice.java b/library/src/main/java/org/mustangproject/CalculatedInvoice.java index 3698a52a..633a18c7 100644 --- a/library/src/main/java/org/mustangproject/CalculatedInvoice.java +++ b/library/src/main/java/org/mustangproject/CalculatedInvoice.java @@ -14,12 +14,33 @@ import java.math.BigDecimal; @JsonIgnoreProperties(ignoreUnknown = true) @JsonInclude(JsonInclude.Include.NON_EMPTY) +/*** + * This is the invoice but with redundant information, i.e. total amount etc. + * It has a calculate function which overwrites this total amount but fundamentally + * it's useful e.g. for imported invoices, because they may have diverging + * amounts, and some users are interested in retrieving the original ones + */ public class CalculatedInvoice extends Invoice implements Serializable { + /*** + * de factor the total net amount + */ protected BigDecimal lineTotalAmount=null; + /** + * still to be paid + */ protected BigDecimal duePayable=null; + /** + * originally to be paid (without prepayments) + */ protected BigDecimal grandTotal=null; + /** + * the net amount upon which value added taxes are applied + */ protected BigDecimal taxBasis=null; + /** + * the total sum of value added taxes + */ protected BigDecimal VATtotal=null; protected TransactionCalculator tc=null; diff --git a/library/src/main/java/org/mustangproject/CashDiscount.java b/library/src/main/java/org/mustangproject/CashDiscount.java index d27b3dcb..afe9722d 100644 --- a/library/src/main/java/org/mustangproject/CashDiscount.java +++ b/library/src/main/java/org/mustangproject/CashDiscount.java @@ -23,6 +23,9 @@ public class CashDiscount implements IZUGFeRDCashDiscount { */ protected Integer days; + /** + * The original payment amount + */ protected BigDecimal basisAmount; /*** @@ -45,6 +48,10 @@ public class CashDiscount implements IZUGFeRDCashDiscount { } + /*** + * how much this discount removed from the original dept + * @return the percent + */ public BigDecimal getPercent() { return percent; } @@ -54,6 +61,10 @@ public class CashDiscount implements IZUGFeRDCashDiscount { return this; } + /*** + * get the number of calendar days this cash discount is valid + * @return the number (integer) of days + */ public Integer getDays() { return days; } diff --git a/library/src/main/java/org/mustangproject/DirectDebit.java b/library/src/main/java/org/mustangproject/DirectDebit.java index eaa1333f..fa0df438 100644 --- a/library/src/main/java/org/mustangproject/DirectDebit.java +++ b/library/src/main/java/org/mustangproject/DirectDebit.java @@ -67,6 +67,11 @@ public class DirectDebit implements IZUGFeRDTradeSettlementDebit { return this.IBAN; } + /*** + * sets the IBAN id (not neccessarily the IBAN, can be anonymized) of the + * @param iBAN the IBAN id (not neccessarily the IBAN, can be anonymized) where the money is deducated + * @return fluent setter + */ public DirectDebit setIBAN(String iBAN) { this.IBAN = iBAN; return this; diff --git a/library/src/main/java/org/mustangproject/EStandard.java b/library/src/main/java/org/mustangproject/EStandard.java index 966e1a21..569c2b71 100644 --- a/library/src/main/java/org/mustangproject/EStandard.java +++ b/library/src/main/java/org/mustangproject/EStandard.java @@ -1,6 +1,35 @@ package org.mustangproject; public enum EStandard { - facturx, orderx, despatchadvice, ubldespatchadvice, zugferd, cii, ubl, ubl_creditnote + /**factur-x/zugferd 2*/ + facturx, + /*** + * order-x + */ + orderx, + /*** + * deliver-x + */ + despatchadvice, + /*** + * 1lieferschein + */ + ubldespatchadvice, + /*** + * ZUGFeRD 1 + */ + zugferd, + /*** + * imported from cross industry invoice + */ + cii, + /*** + * imported from an UBL invoice + */ + ubl, + /*** + * imported from an UBL credit note + */ + ubl_creditnote } diff --git a/library/src/main/java/org/mustangproject/Exceptions/ArithmeticException.java b/library/src/main/java/org/mustangproject/Exceptions/ArithmeticException.java index d0679073..9aaaf60f 100644 --- a/library/src/main/java/org/mustangproject/Exceptions/ArithmeticException.java +++ b/library/src/main/java/org/mustangproject/Exceptions/ArithmeticException.java @@ -3,14 +3,20 @@ package org.mustangproject.Exceptions; import java.text.ParseException; /*** - * will be thrown if an invoice cant be reproduced numerically * ArithmetricException for backwards compatibility, was a spelling error */ public class ArithmeticException extends ArithmetricException { + /*** + * will be thrown if an invoice cant be reproduced numerically + */ public ArithmeticException() { super(); } + /*** + * Exceptions usually are raised with details + * @param details the text + */ public ArithmeticException(String details) { super(details); } diff --git a/library/src/main/java/org/mustangproject/Exceptions/ArithmetricException.java b/library/src/main/java/org/mustangproject/Exceptions/ArithmetricException.java index 16af335b..65199dff 100644 --- a/library/src/main/java/org/mustangproject/Exceptions/ArithmetricException.java +++ b/library/src/main/java/org/mustangproject/Exceptions/ArithmetricException.java @@ -3,14 +3,21 @@ package org.mustangproject.Exceptions; import java.text.ParseException; /*** - * will be thrown if an invoice cant be reproduced numerically + * * (deprecated, because of typo) */ public class ArithmetricException extends ParseException { + /*** + * will be thrown if an invoice cant be reproduced numerically + */ public ArithmetricException() { this(""); } + /*** + * Telling the issue... + * @param details explanation details + */ public ArithmetricException(String details) { super("Could not reproduce the invoice. " + details, 0); } diff --git a/library/src/main/java/org/mustangproject/Invoice.java b/library/src/main/java/org/mustangproject/Invoice.java index 03c29ca7..3345ae7c 100644 --- a/library/src/main/java/org/mustangproject/Invoice.java +++ b/library/src/main/java/org/mustangproject/Invoice.java @@ -173,15 +173,20 @@ public class Invoice implements IExportableTransaction { /*** * BT-17 - * @param dr - * @return + * @param dr the Referenced Document (may contain ID, typecode, date...) + * @return fluent setter */ public Invoice setTenderReferencedDocument(ReferencedDocument dr) { dr.setTypeCode("50");//50 is fixed for tender documents tenderReference=dr; return this; } - + + /*** + * Sets a reference to a tender + * @param ID the key ID of the tender + * @return fluent setter + */ public Invoice setTenderReferencedDocument(String ID) { ReferencedDocument dr=new ReferencedDocument(ID); setTenderReferencedDocument(dr); @@ -192,6 +197,9 @@ public class Invoice implements IExportableTransaction { /** BT-18 */ @Override + /*** + * + */ public IReferencedDocument getObjectIdentifierReferencedDocument() { return objectIdentifierReference; } diff --git a/library/src/main/java/org/mustangproject/ZUGFeRD/CustomXMLProvider.java b/library/src/main/java/org/mustangproject/ZUGFeRD/CustomXMLProvider.java index 211b0103..a7add808 100644 --- a/library/src/main/java/org/mustangproject/ZUGFeRD/CustomXMLProvider.java +++ b/library/src/main/java/org/mustangproject/ZUGFeRD/CustomXMLProvider.java @@ -23,6 +23,9 @@ import java.nio.charset.StandardCharsets; public class CustomXMLProvider implements IXMLProvider { protected byte[] zugferdData; + /*** + * the scope=profile this XML data is provided in + */ protected Profile profile=Profiles.getByName("EN16931"); @Override diff --git a/library/src/main/java/org/mustangproject/ZUGFeRD/DAPullProvider.java b/library/src/main/java/org/mustangproject/ZUGFeRD/DAPullProvider.java index 1d1c28e9..3d388cc9 100644 --- a/library/src/main/java/org/mustangproject/ZUGFeRD/DAPullProvider.java +++ b/library/src/main/java/org/mustangproject/ZUGFeRD/DAPullProvider.java @@ -32,6 +32,9 @@ import org.mustangproject.FileAttachment; import org.mustangproject.Invoice; import org.mustangproject.XMLTools; +/*** + * + */ public class DAPullProvider extends ZUGFeRD2PullProvider { protected IExportableTransaction trans; diff --git a/library/src/main/java/org/mustangproject/ZUGFeRD/IZUGFeRDExporter.java b/library/src/main/java/org/mustangproject/ZUGFeRD/IZUGFeRDExporter.java index ca84cc26..1918761b 100644 --- a/library/src/main/java/org/mustangproject/ZUGFeRD/IZUGFeRDExporter.java +++ b/library/src/main/java/org/mustangproject/ZUGFeRD/IZUGFeRDExporter.java @@ -66,7 +66,24 @@ public interface IZUGFeRDExporter extends Closeable, IExporter { public String getNamespaceForVersion(int ver); public String getPrefixForVersion(int ver) ; public IZUGFeRDExporter disableAutoClose(boolean disableAutoClose); + + /*** + * attach an additional PDF file attachment for Factur-X attachments + * (for attached files embedded into XML, within Germany domestically preferred, + * please refer to @see Invoice.embedFileInXML) + * @param file mime type and data + */ public void attachFile(FileAttachment file); + /*** + * attach an additional PDF file attachment for Factur-X attachments + * (for attached files embedded into XML, within Germany domestically preferred, + * please refer to @see Invoice.embedFileInXML + * + * @param filename the filename to be suggested + * @param data the binary data + * @param mimetype the mime type, from the list of allowed mime types + * @param relation the PDF relation + */ public void attachFile(String filename, byte[] data, String mimetype, String relation); public IXMLProvider getProvider(); diff --git a/library/src/main/java/org/mustangproject/ZUGFeRD/model/DateTimeTypeConstants.java b/library/src/main/java/org/mustangproject/ZUGFeRD/model/DateTimeTypeConstants.java index 895aa899..8707bfba 100644 --- a/library/src/main/java/org/mustangproject/ZUGFeRD/model/DateTimeTypeConstants.java +++ b/library/src/main/java/org/mustangproject/ZUGFeRD/model/DateTimeTypeConstants.java @@ -19,6 +19,9 @@ package org.mustangproject.ZUGFeRD.model; public class DateTimeTypeConstants { + /*** + * the id of the yyyymmdd - Date format + */ public static final String DATE = "102"; public static final String MONTH = "610"; public static final String WEEK = "616"; diff --git a/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentCodeTypeConstants.java b/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentCodeTypeConstants.java index 61cfd66a..97bc92c2 100644 --- a/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentCodeTypeConstants.java +++ b/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentCodeTypeConstants.java @@ -19,9 +19,19 @@ package org.mustangproject.ZUGFeRD.model; public class DocumentCodeTypeConstants { + /*** + * default invoice typecode + */ public static final String INVOICE = "380"; + /*** + * typecode of a credit note, with reference to an invoice. + * Used in all(?) non-german legislations like france to correct a invoice + */ public static final String CREDITNOTE = "381"; public static final String DEBITNOTE = "84"; + /*** + * typecode for a german corrective invoice (negative qtys) + */ public static final String CORRECTEDINVOICE = "384"; public static final String SELFBILLING = "389"; public static final String PARTIAL_BILLING = "326"; diff --git a/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentContextParameterTypeConstants.java b/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentContextParameterTypeConstants.java index d90eabd1..b018ca3c 100644 --- a/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentContextParameterTypeConstants.java +++ b/library/src/main/java/org/mustangproject/ZUGFeRD/model/DocumentContextParameterTypeConstants.java @@ -19,7 +19,16 @@ package org.mustangproject.ZUGFeRD.model; public class DocumentContextParameterTypeConstants { + /*** + * the URN of the guideline ID of a ZUGFeRD 1 basic profile + */ public static final String BASIC = "urn:ferd:CrossIndustryDocument:invoice:1p0:basic"; + /*** + * the URN of the guideline ID of a ZUGFeRD 1 comfort profile + */ public static final String COMFORT = "urn:ferd:CrossIndustryDocument:invoice:1p0:comfort"; + /*** + * the URN of the guideline ID of a ZUGFeRD 1 extended profile + */ public static final String EXTENDED = "urn:ferd:CrossIndustryDocument:invoice:1p0:extended"; } diff --git a/library/src/main/java/org/mustangproject/util/ByteArraySearcher.java b/library/src/main/java/org/mustangproject/util/ByteArraySearcher.java index 9fb83a64..1d1691e6 100644 --- a/library/src/main/java/org/mustangproject/util/ByteArraySearcher.java +++ b/library/src/main/java/org/mustangproject/util/ByteArraySearcher.java @@ -1,5 +1,8 @@ package org.mustangproject.util; +/** + * Find string in large files, text, binary or binary (PDF) + */ public final class ByteArraySearcher { private ByteArraySearcher() { @@ -31,10 +34,22 @@ public final class ByteArraySearcher { return -1; } + /*** + * check if a string or any substring of haystack matches (case sensitive) needle + * @param haystack + * @param needle + * @return true, if haystack contains needle + */ public static boolean contains(byte[] haystack, byte[] needle) { return indexOf(haystack, needle) >= 0; } + /*** + * check if haystack starts with (case sensitive) needle + * @param haystack + * @param needle + * @return true, if haystack immediately starts with needle + */ public static boolean startsWith(byte[] haystack, byte[] needle) { if (needle.length > haystack.length) { return false;