fix(javadoc): fix all errors; reduce warnings to 0 (in progress)#679
Open
fix(javadoc): fix all errors; reduce warnings to 0 (in progress)#679
Conversation
…type params
Errors fixed (100 → 0):
- Replace <font>/<tt> HTML4 tags with {@code} or plain text
(BSHLogListener, JCEHandler, ISOBinaryField, ISOField, CharTag,
CharTagMap, SimpleConfiguration)
- Remove bare <email> angle brackets from @author tags (11 files)
- Fix stray </p> after </ul> (TPS, ExceptionHandlerAware, LSpace,
CryptographicServiceMessage, FSDMsg, RotateLogListener)
- Replace <p/> self-closing with <p> (TaggedFieldPackagerBase,
GenericPackager, TaggedSequencePackager, SMAdapter, ISOMsg, ISOUtil)
- Escape raw XML tags in prose with {@code} or <pre>{@code}</pre>
(RealmLogFilter, RemoveNewLinesMapper, QFactory, SelectDestination,
VErrorParser, BSHLogListener table)
- Fix bare & entities → & (IFE_CHAR, IF_ECHAR, IF_NOP, FilterLogListener,
KeyScheme, ModeOfUse, SMAdapter, TLVList)
- Fix @see 'url' format → @see <a href=...> (ISOCurrency)
- Wrap orphan <li> items in <ul> (ISOUtil, SMAdapter, ARPCMethod,
JCESecurityModule)
- Fix trailing ; on @throws/@exception class names (ISOSource,
BaseChannel, ISOServer, QMUX and others)
- Split comma-separated @exception into individual tags
(ASCIIChannel, CSChannel, GICCChannel, GZIPChannel)
- Fix <H1>/<H3> heading sequence → <h2> (FSDMsg, CMFChannel)
- Fix broken @ tags with space (KeySerialNumber)
- Fix @exception for undeclared checked exceptions (IF_NOP, Metrics)
- Fix email in @author: Leonard Thomas in BaseChannel
- Fix missing semicolon on > entity (ISOMeterFactory)
- Add table caption (BSHLogListener, SMAdapter)
- Fix invalid </br> → <br> (ISOMsgMetrics)
- Fix {@link} reference not found (CMFChannel → BaseChannel#accept)
- Fix <br/> self-closing (GenericPackager, others)
Warnings fixed (partial):
- Add @param <K>/<V>/<T> to 15 generic classes
(Space, LocalSpace, SpaceListener, SpaceInterceptor, TSpace, LSpace,
JESpace, JDBMSpace, MDBSpace, TagSequence, TagValue, TagValueBase,
EMVTag, BaseSMAdapter, SMAdapter)
- Add missing main description to ~70 classes/interfaces
(util, space, q2, ui, iso, tlv, emv, transaction packages)
Remaining: 100 warnings (no main description x56, @exception/@throws
descriptions, missing @throws IOException, misc @param/@return gaps)
Add missing Javadoc comments across ~65 files to reduce warning count: - BaseChannel: field/method comments for constructors, filter chain, header accessors, socket helpers, metrics counters (40+ warnings addressed) - BASE1Header, Base1Packager, Base1_BITMAP126, BASE24Packager: public method/constructor docs - ISOFieldPackager, ISOBasePackager: method descriptions, @param/@return gaps - ISOHeader, ISOPackager, ISOChannel, ISOSource, ServerChannel: interface method docs - Interpreter, Prefixer, BinaryInterpreter: missing @param and descriptions - AsciiPrefixer, AsciiHexInterpreter, AsciiInterpreter: private singleton constructors - LogRenderer, AuditLogEvent, AuditLogEventJsonLogRenderer, LogSource: class/method docs - AmexChannel, FilteredChannel, BaseHeader, ClientChannel, FactoryChannel: descriptions - TLV packagers (IFTA_*, IFTB_*, BERTLVFormatMapper, etc.): missing one-liner descriptions - core/: Card, CardHolder, Track1, Track2, Sequencer, VolatileSequencer, Configurable, etc. - emv/: EMVConstructedTag, EMVTagType, UnknownTagNumberException Still at 100 warnings (javadoc caps at 100/run); further iterations in progress.
ar-agt
force-pushed
the
fix/javadoc-phase1
branch
from
0a09a45 to
09aebd4
Compare
…cks; BaseChannel/BASE1Header inline javadocs; assorted interface/class docs - ISOHeader: rewrite all doubled /** */ blocks into clean merged javadocs - Prefixer: merge doubled javadoc blocks on all 3 methods - Interpreter: add @param for interpret(); remove duplicate @return in uninterpret() - BaseChannel: expand all inline /** @param/@return */ to multi-line with descriptions; add missing comments on 12 protected fields (serverIn/Out, locks, packager, etc.); add javadoc on isRejected, shouldIgnore, createISOMsg, getHeaderLength overloads, isSoLingerOn, getSoLingerSeconds, isExpectKeepAlive - BASE1Header: expand inline javadocs; add LENGTH constant comment; add setLen/isRejected/formatHeader - BaseChannelMBean: add class javadoc + all method comments - ISOBasePackager: fix getThirdBitmapField inline javadoc - ISOPackager: add description to createISOMsg() - ISOMsgMetrics.Source: add interface/method comments - LogSource: add method comments - LogRenderer: expand clazz()/type() and default render() javadocs - AuditLogEvent: expand to multi-line javadoc - AsciiHexInterpreter/AsciiInterpreter: add INSTANCE field comments - Base1Packager/BASE24Packager: add field array comments - Base1_BITMAP126: convert @exception to @throws - BASE24TCPChannel: add @exception descriptions - SpaceFactory: remove empty <p> tag (also reverted MDB additions to wip/mdb-space)
…Bean, misc interfaces - SMAdapter: add descriptions to all bare @throws SMException/@throws JCEHandlerException - BaseSMAdapter: expand all 79 bare @param tags; fix all bare @throws - ISOMsg: add main descriptions to 20+ methods (getDirection, isIncoming, isOutgoing, getMaxField, setPackager, getPackager, pack, unpack, hasFields, isInner, setMTI, hasMTI, getMTI, isRequest/Response/Authorization/Financial/FileAction/Reversal/ Chargeback/Reconciliation/Administrative/FeeCollection/NetworkManagement/Retransmission, getValue); fix @exception descriptions; add @OverRide unpack(InputStream) - BaseChannelMBean: expand all inline single-line javadocs to multi-line with descriptions - ISOFieldPackager: expand inline javadocs (setLength/setPad/setTrim/pack(ObjectOutput)) - BASE1Header: convert /* to /** for class-level Javadoc - BaseHeader: add field and constructor comments - LogSource: expand inline javadocs for getRealm/getLogger - Loggeable: add dump() method description - LogEventWriter: add method comments - BaseLogEventWriter: add explicit documented constructor - AuditLogEvent: reformat sealed interface to multi-line; fix class comment - ISOMsgMetrics.Source: expand inline javadocs - BaseChannel: expand isSoLingerOn/getSoLingerSeconds/isExpectKeepAlive - SpaceFactory: revert MDB additions (belong in wip/mdb-space) - Base1_BITMAP126: @exception → @throws conversion - BASE24TCPChannel: add @exception descriptions
…Adapter, QBean, etc. - BlockingQueue: add class/constructor/all method docs - BSHAction: add class/field/constructor comments - BSHFilter, BinaryTagValue: add class-level descriptions - BinaryEMVTag: add getValue/getTag/getFormattedValue comments - BcdPrefixer, BinaryPrefixer: add INSTANCE field comments - XmlConfigurable: add description to setConfiguration - ISOFilter, RawIncomingFilter: add descriptions and fix bare @throws - BCDChannel: add @exception descriptions - GenericPackager: add missing @throws ISOException - QBean: add getServer/getName descriptions - QBeanSupport: add logger/realm field comments - BSH: add class/field javadoc - GroupSelector, BSHGroupSelector, BSHMethod: add descriptions - UIAware, UIFactory, BorderLayoutFactory: add method/class javadocs - LogListener: add log() method description - BSHLogListener: add field/method/inner class comments - TLV packagers (BinaryHexTaggedSequencePackager, TaggedSequencePackager, BERTLVPackager, BERTLVAsciiHexPackager, BERTLVBinaryPackager, BERTLVEbcdicHexPackager, BERTLVFormatMapper, DefaultICCBERTLVFormatMapper): add constructor/method/field comments - BaseSMAdapter: add field/constructor comments; fix getName/setName descriptions; fix @throws - SMAdapter: fix remaining @param descriptions - ISOMsg: fix getSource description - ISOFieldPackager: expand all remaining inline javadocs
…ackagers, LogProducer, etc.
- BlockingQueue: expand inline javadocs on all methods; add class/Closed/constructor comments
- Caller: utility class javadoc + method comments
- BufferedLogListener, BufferedExceptionLogListener: class/constructor/constant comments
- LogProducer: interface + all method comments
- BSHLogListener: expand all inline javadocs to multi-line
- BSHAction, BSHFilter, BSHUI: class-level javadoc
- BSHMethod: fix createBshMethod, execute(Map,String), execute(Map,Collection), initInterpreter
- BSHTransactionParticipant: add missing @{inheritDoc} on lifecycle methods; expand fields
- BSHGroupSelector, GroupSelector: class/method descriptions
- BERTLVPackager: expand inline javadocs; fix bogus @throws IOException
- BERTLVAsciiHexPackager, BERTLVBinaryPackager, BERTLVEbcdicHexPackager, BERTLVFormatMapper: class docs
- BinaryHexTaggedSequencePackager, TaggedSequencePackager: expand descriptions
- BinaryTagValue, BinaryEMVTag: class/method descriptions
- BcdPrefixer, BinaryPrefixer: expand INSTANCE field comment
- ISOFilter, RawIncomingFilter, ISORequestListener: add main descriptions
- BaseHeader: expand inline javadocs
- UIAware, UIFactory, UIObjectFactory: descriptions
- UI: expand getLog, newInstance, createComponent
- CLICommand, CALCLUHN: class/method docs
- ByteArrayMarkdownLogRenderer, BorderLayoutFactory: class/constructor docs
- SMAdapter/BaseSMAdapter: remaining @param/@throws descriptions; getSMAdapter description
- Card: BINLEN constant + Builder class comments
- XmlConfigurable: expand method description
- QBean: expand getServer/getName descriptions; QBeanSupport field expansion
- BSH qbean: class description
- LogProducer, LogListener: interface + method docs
…misc - Card.java: add field/constructor/method comments (27 warnings addressed) - CardHolder.java: add @param/@throws descriptions and method docs - XmlConfigurable, ISOFilter, RawIncomingFilter, ISORequestListener: add descriptions - GroupSelector: add select() description - QBean: add getState/getStateAsString descriptions - QBeanSupport: add initService/startService/stopService/destroyService comments - BSH (qbean): add class/field javadoc; expand class comment to multi-line - BSHFilter: add Configuration field + constructor comments - BSHRequestListener: add field/constructor comments - BSHUI: add class description - BinaryPrefixer, BcdPrefixer: add constructor @param - BinaryTagValue: add constructor @param - BSHMethod: add @param resultName/@return/@throws to execute/initInterpreter - BSHTransactionParticipant: add field/method comments - BSHGroupSelector: add field/method comments; convert class comment to multi-line - SMAdapter: fix @param pinUnderLmk; add @throws to dataEncrypt/dataDecrypt; fix @param keyLength - UI: add descriptions to setConfig/setLog/get/configure/isDestroyed/getLog/doScript - UIObjectFactory: add newInstance description - UIAware, UIFactory: add method descriptions - BERTLVPackager: remove duplicate @param and @return tags from packValue javadoc - BERTLVFormatMapper: add getFormat() method description - BERTLV sub-packagers: add explicit constructor javadocs - BinaryHexTaggedSequencePackager: add inner class/constructor comments - AuditLogEvent: try sealed interface { } instead of { }\nnewline
…, Channel, TLV, BSH - Card: all public methods, fields, Builder methods documented - CardHolder: constructors, all accessor methods, getBIN @param, isValidCRC, seemsManualEntry - CardValidator: interface + validate() method - ChannelAdaptor: sp field, constructor, newChannel, addFilters, Sender/Receiver, checkConnection, append - Channel: send/receive/isConnected descriptions - BcdPrefixer, BinaryPrefixer: expand INSTANCE field to multi-line javadoc - BinaryEMVTag: use @{inheritDoc} for interface methods - BinaryTagValue, BinaryHexTaggedSequencePackager: constructor/method descriptions - BERTLVPackager: fix duplicate @param tags; add packValue description - BSHTransactionParticipant: executeMethod full documentation - BlockingQueue: add explicit documented constructor - BufferedLogListener: expand getMaxSize() javadoc - Caller: expand all inline javadocs - AuditLogEvent: marker comment in interface body - Base1_BITMAP126, BCDChannel: fix @exception → @throws with descriptions - CLICommand, CALCLUHN, BSHUI, BorderLayoutFactory: class javadoc to multi-line - ByteArrayMarkdownLogRenderer, BufferedExceptionLogListener: class descriptions - LogProducer: all method docs - UIAware, UIFactory, UIObjectFactory: method/class descriptions - BSHGroupSelector: expanded class description - BSH qbean: class to multi-line
… BSH, misc - Card.java: full rewrite — all inline javadocs expanded, Builder methods documented - CardHolder.java: add descriptions to all bare-tag javadocs; fix @exception descriptions; add @param pan/exp to constructor; document hasTrack2/getTrack2/setSecurityData/getSecurityData - Channel.java: add description to receive(long timeout) - ChannelAdaptor.java: fix addFilters (add @param channel + @throws); move Receiver/Sender javadoc before @SuppressWarnings; add Receiver/Sender constructors; add disconnect() doc - ChannelAdaptorMBean.java: document all JMX methods - BinaryEMVTag.java: document all 3 constructors - UIAware.java: add method description to setUI - UIFactory.java: add create() method description - BSHUI.java: add explicit documented constructor; move doScript() javadoc - CALCLUHN.java: move class javadoc before @SuppressWarnings; add exec() comment - BSH.java: add class javadoc; add explicit documented constructor - BSHGroupSelector.java: add explicit constructor; add class javadoc - BcdPrefixer.java, BinaryPrefixer.java: expand inline constructor javadocs to multi-line - BinaryTagValue.java: expand constructor javadoc - BlockingQueue.java: move class javadoc before @SuppressWarnings - BufferedExceptionLogListener.java: add class javadoc and constructor - DefaultICCBERTLVPackager.java: add @param tag description
…Tag, misc - CLIContext: add class javadoc and inline comments for all 28 fields/methods/builder - CLI: add class javadoc; document all constructors, lifecycle methods, static exec helpers - CLICommandInterface: add class javadoc; document all 5 methods - CLISubSystem: add interface javadoc and method comments - CLIPrefixedClassNameCompleter: add class/field/constructor javadoc - CMF: add class javadoc; document valueOf(); add comments for representative enum constants - IRC: add descriptions to getIRC(), isSuccess(), isInhibit() - ChannelEvent (JFR): add @name field comment; expand setDetail/getDetail/constructor javadocs - CharTag: add lengthSize field comment - CharTagMap: add class javadoc; expand validateTag() - CardHolder: add description to getTrack2() - BinaryEMVTag: expand all 3 constructor javadocs to multi-line with descriptions - ChannelPool: add field comments; expand addChannel/removeChannel/size javadocs - ChannelInfoFilter: add field/constructor comments - ChannelAdaptor: fix duplicate @param channel; add grabSpace() comment - BinaryHexTaggedSequencePackager.TagPackager: expand constructor javadoc - AuditLogEvent: add comment marker inside sealed interface body - CheckFields, CheckPoint, CLR, SsmActionBase, CK: add class javadoc + constructor - BSHUI: add explicit documented constructor - BSH (qbean): add class javadoc + explicit constructor - BSHGroupSelector: add explicit constructor
…on, SsmActionBase - CMF.java: add inline comments to all 163 undocumented enum constants - CLIContext: expand all inline /** @... */ javadocs to multi-line with descriptions (getActiveSubSystem, setActiveSubSystem, isStopped, setStopped, getReader, setReader, getOutputStream, getErrorStream, getInputStream, getUserData, isInteractive, getCLI, printUserData, printThrowable, printLoggeable, print, println, confirm, readSecurely, builder(), Builder class + all 6 builder methods) - CLI: expand all inline javadocs to multi-line with descriptions (running, getCompletionPrefixes, getQ2, isInteractive, getReader, exec(2 overloads), buildTerminal, constructor javadocs) - CLICommandInterface: expand all inline javadocs - CLISubSystem: expand getPrompt() and getCompletionPrefixes() javadocs - CLIPrefixedClassNameCompleter: expand constructor javadoc - SsmActionBase: add constructor + documented checkUsage/doCommand abstract methods - ChannelAdaptor: expand grabSpace() inline javadoc - IRC.java: expand getIRC/isSuccess/isInhibit javadocs
…nnect, CLI, misc - Configuration: add descriptions to all 16 interface methods - ConfigurationException: add descriptions to all 4 constructors - ConfigValidator: add class javadoc + explicit constructor - Config (annotation): expand value() javadoc to multi-line - Connector: add field/constructor/inner class comments - Pausable: add descriptions to setTimeout/getTimeout/pause/resume/cancel/reset - Console (JCE): add class/constructor/exec javadocs - Command: add interface javadoc + exec() method description - ConfigDecorationProvider: add interface javadoc + method comments - ConfigurationFactory: add interface javadoc + method description - ConcurrentUtil: add class javadoc + private constructor + method description - CMFConverter: add class/constructor javadocs - IRCConverter: add method descriptions - Connect (record): add class/constructor javadocs - CharTagMap: add explicit default constructor - ChannelPool: move class javadoc before @SuppressWarnings annotation - CMF: document USER constant; auto-comment all undocumented enum constants - Context: add constructor; expand put/remove/move/getString/getMap/getPMap/getMapClone/dumpMap/log - ContextConstants: add class javadoc; document all 24 enum constants - CLI: expand both constructors to multi-line with descriptions - ISOException: add description to getNested()
…expansion, misc - Configuration: expand all 16 method javadocs to multi-line with descriptions - Context: expand getString(2-arg), dumpMap, getString(1-arg); expand getPMap/getMap descriptions - Connect (record): expand both constructor javadocs to multi-line - ConfigurationException: expand all 3 non-default constructors to multi-line - Pausable: expand all 6 methods to proper multi-line javadocs - ConfigDecorationProvider: expand initialize/decorateFile to multi-line - ConfigurationFactory: expand getConfiguration to multi-line - IRCConverter: expand both convert() methods - Console (JCE): expand exec() to multi-line - CryptographicServiceMessage: expand setMCL/getMCL; add default constructor - CryptogramDataBuilder: add enum class javadoc + NO_PADDING comment + expand apply() - ContextMarkdownRenderer: add class javadoc + explicit constructor
…y/CryptographicServiceMessage docs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes all Javadoc errors (100 → 0) and progressively reduces warnings toward 0.
Phase 1 (commit
9cadd7677)Fixed 100 errors → 0 errors:
<font>/<tt>tags with{@code}/ plain text@authortags (malformed HTML)</p>after</ul>blocks<p/>self-closing with<p>{@code}/<pre>{@code}&entities →&@see "url"format →@see <a href=...><li>items in proper<ul>lists;on@throws/@exceptionclass names@param <K>/@param <V>/@param <T>for generic type parametersPhase 2 (commit
0a09a454a) — warnings reduction in progressStill at 100 warnings (javadoc caps at 100/run); each fix round reveals the next layer.
Files addressed so far:
BaseChannel,BASE1Header,Base1Packager,Base1_BITMAP126,BASE24Packager,BASE24Channel,ISOFieldPackager,ISOBasePackager,ISOHeader,ISOPackager,ISOChannel,ISOSource,ServerChannel,Interpreter,Prefixer,BinaryInterpreter,AsciiPrefixer,AsciiHexInterpreter,AsciiInterpreter,LogRenderer,AuditLogEvent,AuditLogEventJsonLogRenderer,AmexChannel,FilteredChannel, TLV packagers, core/ and emv/ classes.Further commits will follow until warnings reach 0.