A try at documentation and automated UML diagrams
Over the couple of last few days, I’ve been working on an Issue at TravelMate’s repository which concerns documenting the app by using automated UML (Unified Modeling Language) diagrams. I opened the Issue myself last November of 2018 and has only gained traction in February due to people that want to contribute to it. I finally got to it and made the corresponding Pull Request. I chose to work on a documentation issue because mainly I wanted to explore how the documentation process for a software project can develop and how it will be useful for the developers and maintainers of the project.
How to generate UML Diagrams for an Android Project in Android Studio
As stated in the Issue, I wanted to use automated UML diagram generation so that the documentation process can be done more efficiently compared to generating UML diagrams manually. Thus, I had to find a solution that would work for Android Studio projects. With some searching around, I came across SimpleUML. It’s a plug-in intended for IntelliJ and subsequently made compatible for Android Studio. Although I was skeptical to try it due to the comments at its page stating that the plug-in is not working properly, I nevertheless tried it still and managed to get it to work.
If the recording is way too small for your screen, open the GIF file in a new tab by right-clicking it and selecting “Open image in new tab” option. If you want the step-by-step instructions for it:
- Open Android Studio and the Android project you want to work on for.
- Click the “File” option in the top left of the screen
- Click “Settings” option then select the “Plugins” option.
- Click the “Browse Repositories” option and it should open up a new dialog box.
- Look for the search tab as indicated by the Magnifying Glasses icon. Type in “SimpleUMLCE” in the tab.
- Once you find the “SimpleUMLCE” plug-in, click the green “Install” button and proceed with the installation instructions as directed. You will need to restart your Android Studio for the plug-in to work
Generating UML Diagrams:
Now that SimpleUML plugin is installed, you need to generate the UML diagrams automatically for a target file that you want:
- Right-click the target Java/Kotlin file that you want to generate UML diagrams for then select the “Add to SimpleUML Diagram” -> “New Diagram” option located near the bottom of the selection box.
- Follow the instructions on the new dialogue box of “Create A New Diagram” by giving your diagram a name. SimpleUML would automatically determine to save the file in the current folder of the Android project you’re working on. If you want to change it, click the 3-dots button and select a new folder. Be wary that the plug-in itself doesn’t support creating new folder within the dialog box, so create a new folder on your file explorer before selecting a new folder in the dialog box.
- Now that you successfully completed all the steps, a UML diagram that looks like below should be presented to you:
The PR that I made basically contains UML diagrams similar to the one above. If you don’t understand UML diagrams and this is your first time seeing them, let me run a quick introduction to them.
What are UML diagrams?
UML Diagrams are basically diagrams that document how a software project is structured. It does this by representing the functions/routines that are present within a file and giving it the appropriate graphical representations. UML diagrams can be much more complex than the one featured above but for the sake of simplicity and practicality in using these for our specific kind of purpose, the UML diagrams that will be generated by SimpleUML will mostly look the same as the one in the screenshot above.
In the screenshot above, you have the file name at the very top of the blue box. In the case of the function “CardViewOptionsAdapter”, it’s name is displayed in the very top and its fields (read: variables) are listed under a section called ‘fields’. The functions within the file are listed under a section called ‘methods’ and you can see from the screenshot above that it has a “onCreateViewHolder” function in the file. Every UML diagram generated using SimpleUML will follow these patterns.
With a UML diagram above, future developers that have the SimpleUML plug-in installed can see the functions in multiple files and use it to better understand how a software project is structured.
Other Issues and projects I’m looking at
Since my last targeted Issue of Brave Browser for Android didn’t work out well due to the errors that I encountered when making the Android project work at my computer (read: Being unable to dual-boot Ubuntu and Windows at my home PC) and using a Virtual Machine w/ Ubuntu installed on it seemed a very impractical setup due to how much resource Android Studio needs to run, I decided to be more careful and only work on projects which have a clear documentation for setting up the project and which will build and run on the Windows platform. Thus, I picked the WordPress Mobile For Android project and chose to look at this particular Issue.