documentation based on source codes

[Igor Janick]

There is a runtime database existing in the form of classes (say beans). Many of them contain lists of another ones. They are written mostly in Kotlin. The advantage is: they are in a separated package (with a few subpackages).
I have to extract documentation with attributes.
There is no relational database below. The data is imported from a server.

So I am looking for a tool to make it.
They expect me to make the documentation as for database.

Note: not JavaDoc.

[Tim Moores]

I have to extract documentation with attributes.

What does this mean? Do you have to write or otherwise create the documentation? What should that documentation include?

Note: not JavaDoc.

Why not? Are you aware of https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html?

[Tim Holloway]

Without actually checking, I'm pretty sure that the Android Studio IDE can "javadoc" Kotlin code just as easily as it can actual Java. The problem then is how well the code itself was designed and commented. A well-designed system could output a complete professional-quality technical manual all by itself. A less well-designed system will put out something more like what you get from Oracle.

If JavaDoc is forbidden then you have idiot management. If it's simply not producing usable output, then likely the code isn't self-documenting to begin with and you're going to have to do it the hard way. JavaDoc is one of the best tools around. It's a descendant of pre-Java auto-documenting tools such as the AutoDoc system that Commodore used to create their Amiga technical manuals, and serves as an inspiration for other tools such as Doxygen.

And incidentally, JavaDoc doesn't have to output stuff that looks like it came straight from Oracle. There are a LOT of customization options for it besides the stock tabular displays. It can even produce documents with graphics in them.

[Igor Janick]

My employer expects me to prepare DOCX file with description of these classes.
The previous document was a design with relative database scheme and description. However, development of the project went a different way. It took some years.

A cumbersome approach is to prepare a shell script (say: in PERL) extracting the data from source files using RegExp. However, I do hope there is something ready to use.

[Tim Holloway]

DOCX (Microsoft Word format) is an output option for JavaDoc. So is PDF, which is what I'd recommend unless you specifically intend to edit the documentation*. If memory serves, the primary output is HTML which can then be converted as needed. So you can make things pretty using CSS, for example.

As to whether or not you could extract a schema documentation via JavaDoc depends a lot on how the schema is encoded into the logic. It should be fairly easy if you're using something like JPA (including Android Rooms).

JavaDoc does support plugins in case its basic capabilities don't suit.

I did, in fact create my own auto-doc system (in AWK) for work I was doing in Visual C++ back before Java came out. But just as with JavaDocs, it worked best when the source code had been created with automated documentation in mind.

===
* The reason I recommend PDF for formal documents is to make it harder for people who don't know as much as they think they do to come along and muck it up after it has been produced.

[Igor Janick]

There is no persistence API. There are only classes which constructs something like database in memory.

[Tim Holloway]

I wasn't referring to an API, but rather the fact that in ORM-like systems the tables each are defined in a class and the fields (columns) are mapped to properties of class. The important thing is that there be some sort of simple structure that a processor can grab and digest.

[Igor Janick]

Finally, I have written a script (PERL) extracting name  of classes and their attributes.
I have found two usable tools to draw a diagram.

https://www.quickdatabasediagrams.com/
https://dbdiagram.io/home

At present, I try to use the first one. The output of the script generates data with syntax for it. The shortcomming is that I have to define relations manually.


The second one allows automating also relations, however it is designed for tables not classes.
I can easily tailor the script to write relevant syntax, but there is not so clear with relations.


Do you know any other easy to use tools for diagrams drawing automation ?

Enclosed a trial output from: quickdatabasediagrams.com

[Igor Janick]

P.S. The script-generated data for aforesaid diagram looks like:

"api.dto.model.CardPaymentData"
-
uniqueId String
tid String
referenceNumber String
paymentCryptogramData String
amountInPLN String
currencyCode String
exchangeRateExponent String
dccErrorCode String
hiddenCardNumber String
realisationType String
exchangeRateDate String
exchangeRateExpirationDate String
transactionProcessingInfo String
transactionConfirmationInfo String

"api.dto.model.CashState"
-
confirmationDate DateTime
currency String
amount BigDecimal
employee String
loadNumber String
safeEnvelopeNumber String

"api.dto.model.ChangedDictionary"
-
dictionaryName String
dictionaryVersion DateTime
dictionaryEntries List<DictionaryEntry>
operation Operation

"api.dto.model.DictionaryEntry"
-
key String
value String

"api.dto.model.DictionaryVersion"
-
dictionaryName String
dictionaryVersion DateTime

[Tim Holloway]

I'm a very firm proponent of graphviz. It's an automated diagramming tool developed originally, I think, by Bell Labs. It's really good for drawing relationships and linked tables, although it does tend to have a mind of its on on where to put them. The GraphViz language is quite simple and easy to generate by machine or manually.

For existing databases, I like SchemaSpy. It uses a JDBC driver to completely reverse-engineer a SQL database including fields, foreign keys, comments, and so forth.

[Ron McLeod]

I'm a big fan of Graphviz and some of the applications like PlantUML that are built on top of it.

[Igor Janick]

Thanks. Graphviz looks prospective. But now I have to complete my job ASAP. So I try both quickdatabasediagrams and dbdiagram.
The second one seems to be more usable hovever the output is limited to PNG file. The first one provides also SVG which would let me to align tables maually.