This week's giveaway is in the Testing forum.
We're giving away four copies of TDD for a Shopping Website LiveProject and have Steven Solomon on-line!
See this thread for details.
Win a copy of TDD for a Shopping Website LiveProject this week in the Testing forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Paul Clapham
  • Ron McLeod
  • Jeanne Boyarsky
  • Tim Cooke
Sheriffs:
  • Liutauras Vilda
  • paul wheaton
  • Henry Wong
Saloon Keepers:
  • Tim Moores
  • Tim Holloway
  • Stephan van Hulst
  • Carey Brown
  • Frits Walraven
Bartenders:
  • Piet Souris
  • Himai Minh

documentation based on source codes

 
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Saloon Keeper
Posts: 7314
170
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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?
 
Saloon Keeper
Posts: 25459
180
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Saloon Keeper
Posts: 25459
180
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
There is no persistence API. There are only classes which constructs something like database in memory.
 
Tim Holloway
Saloon Keeper
Posts: 25459
180
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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



diagram-Kotlin-1-.png
[Thumbnail for diagram-Kotlin-1-.png]
 
Igor Janick
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
P.S. The script-generated data for aforesaid diagram looks like:

 
Tim Holloway
Saloon Keeper
Posts: 25459
180
Android Eclipse IDE Tomcat Server Redhat Java Linux
  • Likes 2
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.

 
Marshal
Posts: 3825
537
Android Eclipse IDE TypeScript Redhat MicroProfile Quarkus Java Linux
  • Likes 1
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I'm a big fan of Graphviz and some of the applications like PlantUML that are built on top of it.
 
Igor Janick
Greenhorn
Posts: 20
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
You ridiculous clown, did you think you could get away with it? This is my favorite tiny ad!
free, earth-friendly heat - a kickstarter for putting coin in your pocket while saving the earth
https://coderanch.com/t/751654/free-earth-friendly-heat-kickstarter
reply
    Bookmark Topic Watch Topic
  • New Topic