This is a reply to some questions about the OOE UML diagrams from a Drupal.org contributor, moved to here from a Drupal API feature request issue (Would like to be able to include links to images in Class/Interface/Namespace docs) since a bit off-topic:
I have resumed my work on my "OOE = Object Oriented Examples = One Of Each" project in earnest, and hope to make a major Drupal.org OOE sandbox commit of the code later this week. If you visit that link, you'll see I'm working towards completing a sweep of the UML diagrams for each every class in the educational demonstration module OOE: OOE UML, OOE UML gallery.
I will be making a community forum announcement about the OOE project on Drupal.org. In the meantime, some quick remarks on UML diagramming as it relates to the OOE module vs. Drupal core.
Remarks and question:
Your diagrams are very interesting. Are those all generated by PEAR PHP UML or hand edited?
They are definitely hand-edited, and they use a very systematic modelling recipe that I developed as a consultant to the developers of the MagicDraw UML tool, adapted here for PHP. I use PEAR PHP UML to generate an XMI file, and then I import that (and update the import frequently) to create/update Class elements, which according to the recipe are denoted design(ed) Classes.
However, because even with type hinting PHP does not lend itself well (not perfectly) to associative graphical UML modelling, I use a special technique I have developed and promoted for over a decade called UML2 Component wrapping; I perform associative modelling on UML2 Components, denoted the "analysis" model, which "wrap" matching "design(ed)" classes. The design(ed) Classes are never edited or changed in any way in the UML project file, except during XMI project re-import; the UML2 "wrapper" Component analysis elements "parasitically" model those design(ed) Classes. Thus one can perform complete systems engineering modelling in the analysis domain, without the restrictions due to the PHP design(ed) model. This technique is incredibly powerful, and MagicDraw UML has in fact been tuned during its development to support it (because I worked for them).
There is absolutely no way that kind of advanced modelling can be automated; it requires human intervention. Also, it is the very act of modelling this way that helps one understand the system better. In other words, it has to pass through my brain and fingers (rather than a machine's silicon bits and bytes) and this reinforces understanding.
Also, it requires a very strict coding style (illustrated in detail by my OOE project and the dedicated OOE module zone) that is specifically chosen to be amenable to reverse engineering to UML; although for example Drupal8 incorporates a move towards more object-orientation, it is not engineered parallel with graphical UML-driven software/systems engineering techniques, so it does not lend itself well to UML modelling.
Remarks and question:
We use https://github.com/clemens-tolboom/uml-generator-php together with https://github.com/nikic/PHP-Parser ... can we team up to make api.d.o better?
That has value, and I am glad that you are doing it, I welcome any interest in UML, especially for Drupal, but there are 2 main things I would remark on:
1. The OOE = Object Oriented Example = One of Each project is not a model of Drupal7 core; it is an object-oriented bridge to the Drupal7 contributed module API, it enables one to operate entirely in an object-oriented space, with objects that know how to handle Drupal structured arrays and pass them off to Drupal core, along with page controllers and form controllers that permit one to work with the Drupal hooks, but encapsulated in Classes.
2. I am definitely going to also do UML modelling of Drupal8 core, but those models will be of a very different nature to both the OOE object-oriented bridge project, and also very different from your api.d.o documentation project. I am using a technique I developed and promote called UML Parsing Analysis, which combines text parsed from documentation (in this case the Drupal.org docs for Drupal8) with reverse engineered Classes (according to the recipe the design layer), both brought together by being "wrapped" by UML2 Components. Again, this technique is optimised for MagicDraw UML, and it very unlikely that anybody else would be able to apply the recipe the way I can, at least not until I have made the first announcement of my Drupal8 core models so they can see the recipe in action. The recipe can be adapted to tools other than MagicDraw UML, but the recipe as I will be using it to will only work in MagicDraw UML.
Darren Kelly, Webel IT Australia
© Copyright 2001 - 2016 Webel IT Australia (ABN: 67 677 268 579). All rights reserved (except as specified below).
PHP code examples from Webel IT Australia on this site are distributed under the GNU General Public License.
Excludes text and code snippets from Drupal.org quoted for educational purposes.
Drupal’s online documentation is © 2000-2014 by the individual contributors and can be used in accordance with the Creative Commons License, Attribution-ShareAlike 2.0.
PHP code from Drupal.org is distributed under the GNU General Public License.
Drupal® is a registered trademark of Dries Buytaert.
Text quoted from Wikipedia for educational purposes is made available under the Creative Commons Attribution-ShareAlike License.
Wikipedia® is a registered trademark of the Wikimedia Foundation, Inc., a non-profit organization.
Site developed by Webel IT Australia.