From 7a8cd5925bd911b746d5395924e057a8232dafc4 Mon Sep 17 00:00:00 2001 From: Bartek Kryza Date: Fri, 1 Apr 2022 23:19:09 +0200 Subject: [PATCH] Updated README --- README.md | 119 ++++++++++++++++++++------------ docs/img/puml_aggregation.png | Bin 0 -> 402 bytes docs/img/puml_association.png | Bin 0 -> 865 bytes docs/img/puml_composition.png | Bin 0 -> 444 bytes docs/img/puml_dependency.png | Bin 0 -> 965 bytes docs/img/puml_inheritance.png | Bin 0 -> 933 bytes docs/img/puml_instantiation.png | Bin 0 -> 605 bytes docs/img/puml_nested.png | Bin 0 -> 725 bytes 8 files changed, 75 insertions(+), 44 deletions(-) create mode 100644 docs/img/puml_aggregation.png create mode 100644 docs/img/puml_association.png create mode 100644 docs/img/puml_composition.png create mode 100644 docs/img/puml_dependency.png create mode 100644 docs/img/puml_inheritance.png create mode 100644 docs/img/puml_instantiation.png create mode 100644 docs/img/puml_nested.png diff --git a/README.md b/README.md index df3c4bef..55031611 100644 --- a/README.md +++ b/README.md @@ -5,9 +5,11 @@ `clang-uml` is an automatic C++ to [PlantUML](https://plantuml.com) class, sequence and package diagram generator, driven by YAML configuration files. The main idea behind the project is to easily maintain up-to-date diagrams within a code-base or document -existing project code. The configuration file or files for `clang-uml` define the +legacy code. The configuration file or files for `clang-uml` define the type and contents of each generated diagram. +`clang-uml` currently supports C++ up to version 17. + ## Features Main features supported so far include: @@ -16,9 +18,9 @@ Main features supported so far include: * Class relationships including associations, aggregations, dependencies and friendship * Template instantiation relationships * Relationship inference from C++ containers and smart pointers - * Namespace based content filtering + * Diagram content filtering based on namespaces, elements and relationships * Optional package generation from namespaces - * Interactive links to online code to classes, methods and class fields + * Interactive links to online code to classes, methods and class fields in SVG diagrams * Sequence diagram generation * Generation of sequence diagram from one code location to another (currently only for non-template code) * Package diagram generation @@ -30,7 +32,7 @@ To see what `clang-uml` can do so far, checkout the diagrams generated for unit ## Installation ### Building from source -Currently the only method to install `clang-uml` is from source. First make sure +Currently, the only method to install `clang-uml` is from source. First make sure that you have the following dependencies installed: ```bash @@ -120,9 +122,9 @@ diagrams: - 'note left of {{ alias("MyProjectMain") }}: Main class of myproject library.' ``` -See ![here](docs/configuration_file.md) for detailed configuration file reference guide. +See [here](docs/configuration_file.md) for detailed configuration file reference guide. -### Examples +## Examples To see what `clang-uml` can do, checkout the test cases documentation [here](./docs/test_cases.md). In order to see diagrams for the `clang-uml` itself, based on its own [config](.clang-uml) run @@ -169,44 +171,6 @@ generates the following diagram (via PlantUML): > Open the raw image [here](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t00009_class.svg), > and checkout the hover tooltips and hyperlinks to classes and methods. -#### Default mappings - -| UML | C++ | -| ---- | --- | -| Inheritance (A is kind of B) | Public, protected or private inheritance | -| Association (A knows of B) | Class A has a pointer or a reference to class B, or any container with a pointer or reference to B | -| Dependency (A uses B) | Any method of class A has argument of type B | -| Aggregation (A has B) | Class A has a field of type B or an owning pointer of type B | -| Composition (A has B) | Class A has a field of type container of B | -| Template (T specializes A) | Class A has a template parameter T | -| Nesting (A has inner class B) | Class B is an inner class of A -| Friendship (A is a friend of B)| Class A is an friend class of B - -#### Comment decorators - -`clang-uml` provides a set of in-comment directives, called decorators, which allow custom control over -generation of UML diagrams from C++ and overriding default inference rules for relationships. - -The following decorators are currently supported: -- [note](docs/test_cases/t00028.md) - add a PlantUML note to a C++ entity -- [skip](docs/test_cases/t00029.md) - skip the underlying C++ entity -- [skiprelationship](docs/test_cases/t00029.md) - skip only relationship generation for a class property -- [composition](docs/test_cases/t00030.md) - document the property as composition -- [association](docs/test_cases/t00030.md) - document the property as association -- [aggregation](docs/test_cases/t00030.md) - document the property as aggregation -- [style](docs/test_cases/t00031.md) - add PlantUML style to a C++ entity - -##### Doxygen integration -`clang-uml` decorstors can be omitted completely in ![Doxygen](https://www.doxygen.nl/index.html), by adding the following -lines to the Doxygen config file: - -``` -ALIASES += clanguml="" -ALIASES += clanguml{1}="" -ALIASES += clanguml{2}="" -ALIASES += clanguml{3}="" -``` - ### Sequence diagrams #### Example @@ -335,6 +299,73 @@ generates the following diagram (via PlantUML): ![package_diagram_example](docs/test_cases/t30003_package.svg) + +### Default mappings + +| UML | PlantUML | +| ---- | --- | +| Inheritance | ![extension](docs/img/puml_inheritance.png) | +| Association | ![association](docs/img/puml_association.png) | +| Dependency | ![dependency](docs/img/puml_dependency.png) | +| Aggregation | ![aggregation](docs/img/puml_aggregation.png) | +| Composition | ![composition](docs/img/puml_composition.png) | +| Template specialization/instantiation | ![specialization](docs/img/puml_instantiation.png) | +| Nesting (inner class/enum) | ![nesting](docs/img/puml_nested.png) | + +### Diagram content filtering +For typical code bases, generating a single diagram from entire code or even a single namespace can be too big to +be useful, e.g. as part of documentation. `clang-uml` allows specifying content to be included and excluded from +each diagram using simple YAML configuration: + +```yaml +include: + # Include elements from 2 namespaces + namespaces: + - clanguml::common + - clanguml::config + # Include all subclasses of ClassA (including ClassA) + subclasses: + - clanguml::common::ClassA + # Include only inheritance relationships + relationships: + - inheritance + # Include only classes in direct relation to ClassB (including ClassB) + context: + - clanguml::common::ClassB +exclude: + # Exclude all elements from detail namespace + namespaces: + - clanguml::common::detail + # Exclude ClassF + exclude: + - clanguml::common::ClassF +``` + +### Comment decorators + +`clang-uml` provides a set of in-comment directives, called decorators, which allow custom control over +generation of UML diagrams from C++ and overriding default inference rules for relationships. + +The following decorators are currently supported: +- [note](docs/test_cases/t00028.md) - add a PlantUML note to a C++ entity +- [skip](docs/test_cases/t00029.md) - skip the underlying C++ entity +- [skiprelationship](docs/test_cases/t00029.md) - skip only relationship generation for a class property +- [composition](docs/test_cases/t00030.md) - document the property as composition +- [association](docs/test_cases/t00030.md) - document the property as association +- [aggregation](docs/test_cases/t00030.md) - document the property as aggregation +- [style](docs/test_cases/t00031.md) - add PlantUML style to a C++ entity + +### Doxygen integration +`clang-uml` decorstors can be omitted completely in [Doxygen](https://www.doxygen.nl/index.html), by adding the following +lines to the Doxygen config file: + +``` +ALIASES += clanguml="" +ALIASES += clanguml{1}="" +ALIASES += clanguml{2}="" +ALIASES += clanguml{3}="" +``` + ### Test cases The build-in test cases used for unit testing of the `clang-uml`, can be browsed [here](./docs/test_cases.md). diff --git a/docs/img/puml_aggregation.png b/docs/img/puml_aggregation.png new file mode 100644 index 0000000000000000000000000000000000000000..274fae3e196879c6e333cc638b25a13e776fbee9 GIT binary patch literal 402 zcmV;D0d4+?P)L6rubQdxd+Ae}?e}NDR`4J-0KhRDtf}`zF#Jz2t-342k zLHafa!DbPB?{v@##kANAz69?#CU3Z$+{Yn`Bq6rqxgMa5B(xlUghpds%uy=eq0w4Q zIz8O&pJ3AIfmXs>#{+;g(TJ-Nbbo~4rUl&}A+AP96YYAwVj8!*yxlwIxZR~Sh9qf? zVb*i;3ByX0^XV+}<$OBhu+rqFGyjpYABJjYeTmXo#I*=-PtSONdHusXP++oY+w=TJ z9fKfTY0PDl4uTMVqmJ7BC3X*d$Dg-26iKFu#=~g~0C0F7;_>1N0C04DCShe+uADUH w?b^Q!$9I>*;!kvXPa_K|;%60o0=k^UuQ|+5i9m07*qoM6N<$f+kL@1^@s6 literal 0 HcmV?d00001 diff --git a/docs/img/puml_association.png b/docs/img/puml_association.png new file mode 100644 index 0000000000000000000000000000000000000000..bcb0e9f6197ddd62bce0307461a7a0c2dec7e186 GIT binary patch literal 865 zcmV-n1D^beP)EX>4Tx04R}tkvmAkP!xv$K17j10C8=2pe-SA-FOfMLXCW*Kvml!9-4-BT~sU5sb>_x)LYYTjZ%KqQ`JhG`RT5KnK~ z2IqZZft6&H_?&p$qze*1a$WKGjdRiEAkP%cOnRPJAQp=qtaLCdnHupFaa7fG$`58e zRyl8R)+#mDx+i~OB(JY5bDh=*l32tNB#2N@Lm3s=h|#W-Vj)fE2_OHE>zBx-kgE(v zjs;YqL3aJ%fAD*@R$(&kB}EcI*NfwPi~`-eK(p>R-^Y&AJOM(_z?I(iR~x|0C+YRJ z7Ci#`w}Ff6wx;X>mpj1VlOdb3D}`tU3kBf)jJ_!c4BP^}Yu?;i=Qw=;GBm5y4RCM> zj1?(+-RIpsopbxQr!~JHZKraj2lJvw00006VoOIv0RI600RN!9r;`8x010qNS#tmY z3ljhU3ljkVnw%H_000McNliru<^%y0ASx8)bwU6D02y>eSad^gZEa<4bO1wgWnpw> zWFU8GbZ8()Nlj2!fese{00B8kL_t(o!|m6-O2beX#_=Z~tyQr@QA-!;Bw1W^5Ne5w zh+sww=1X|Lt9WoO3v@ zB!m#4`bs7OLK{39b3Igz0s`A1scvY&orCN394u`Oi8&2%ElpCP)bQ|deuewJA{y2O z7M{;SNggPW0Pp*haA`b3)V6F!_ zszNUtNG=oDpJ=66R(!NLN%VC+dHZJ=o1Ox123RQN=q>vvrRdum?AeEZTLXK1figUV zx_O52%nU};DH7^*J;Q61y<@`OJ_LJeLLG@gw|42obwm5Eae4`RYaiZC4cVhjg6jn> ryb(AD7E-Gj`r!78M$y7fXoKtv0_t}_R4!lk00000NkvXXu0mjfr(kZ1 literal 0 HcmV?d00001 diff --git a/docs/img/puml_composition.png b/docs/img/puml_composition.png new file mode 100644 index 0000000000000000000000000000000000000000..083169c9d56192be95e65616c42822c82b5cfd6a GIT binary patch literal 444 zcmV;t0YmLE$;NmE>D0C=DC&dro(of(b4hk-U4lbS4Rd8sb z;CCoa9d(c*3W|thX$*qt-E;77NwwIaN#TBLmdE4WaS5Sco$Gs4a_eyKollOrrGK8H|+?F$RNDB)1z47 zW{u4y;W;kc+ehC=VG7uZ7>1@3NS*8;nw$zCV)z&{`DHX4FNkO7Aq`II>>%to(E0wvWP|l_R0000EX>4Tx04R}tkvmAkP!xv$K17j10C8=2pe-SA-FOfMLXCW*Kvml!9-4-BT~sU5sb>_x)LYYTjZ%KqQ`JhG`RT5KnK~ z2IqZZft6&H_?&p$qze*1a$WKGjdRiEAkP%cOnRPJAQp=qtaLCdnHupFaa7fG$`58e zRyl8R)+#mDx+i~OB(JY5bDh=*l32tNB#2N@Lm3s=h|#W-Vj)fE2_OHE>zBx-kgE(v zjs;YqL3aJ%fAD*@R$(&kB}EcI*NfwPi~`-eK(p>R-^Y&AJOM(_z?I(iR~x|0C+YRJ z7Ci#`w}Ff6wx;X>mpj1VlOdb3D}`tU3kBf)jJ_!c4BP^}Yu?;i=Qw=;GBm5y4RCM> zj1?(+-RIpsopbxQr!~JHZKraj2lJvw00006VoOIv0RI600RN!9r;`8x010qNS#tmY z3ljhU3ljkVnw%H_000McNliru<^%y0ARzQGoLm3^02y>eSad^gZEa<4bO1wgWnpw> zWFU8GbZ8()Nlj2!fese{00EszL_t(o!(;sa|Nno6Q9u%48V!QcKpXf#`}yVr!_B^B z44-a17!4^xf%fV81BNr{?F`#A!We{%H5m9b6h=b|39uk@UhF=_aBISHhUeRkF)*{U zG1%{zz#wXGG#X0if%fm`FNTN9b}`)OUCQw5{U?S$U%oRiv9Uq|%)xjxgs=d{^sd5^_^^S$u^>t)3XqLxemAhOsgW+21d_!MgxwRKtt{kJXo}iLDI`= nw1G=(ppAmj4*O`J4I}^nS}B(;%W*}I00000NkvXXu0mjfd`Gb0 literal 0 HcmV?d00001 diff --git a/docs/img/puml_inheritance.png b/docs/img/puml_inheritance.png new file mode 100644 index 0000000000000000000000000000000000000000..1766929dbc90b009f53cc2fc38208c3cd773c007 GIT binary patch literal 933 zcmV;W16urvP)EX>4Tx04R}tkvmAkP!xv$K17j10C8=2pe-SA-FOfMLXCW*Kvml!9-4-BT~sU5sb>_x)LYYTjZ%KqQ`JhG`RT5KnK~ z2IqZZft6&H_?&p$qze*1a$WKGjdRiEAkP%cOnRPJAQp=qtaLCdnHupFaa7fG$`58e zRyl8R)+#mDx+i~OB(JY5bDh=*l32tNB#2N@Lm3s=h|#W-Vj)fE2_OHE>zBx-kgE(v zjs;YqL3aJ%fAD*@R$(&kB}EcI*NfwPi~`-eK(p>R-^Y&AJOM(_z?I(iR~x|0C+YRJ z7Ci#`w}Ff6wx;X>mpj1VlOdb3D}`tU3kBf)jJ_!c4BP^}Yu?;i=Qw=;GBm5y4RCM> zj1?(+-RIpsopbxQr!~JHZKraj2lJvw00006VoOIv0RI600RN!9r;`8x010qNS#tmY z3ljhU3ljkVnw%H_000McNliru<^%y0APy+zk&^%b02y>eSad^gZEa<4bO1wgWnpw> zWFU8GbZ8()Nlj2!fese{00DhTL_t(o!|j+qNJ3E*#=ln@k!2x)gy}1sf}%xmh#bm% zE+NrBo=y#o?T$fvds9lhk`!B7~4+i7B@=@R5mb_kR1i!;f>% z_npHLLI~QR?_vphqX9Iiqm|-Xxq{4L9ErssB4#gWk*?VSQmr8$PeBRA@DjO($uR~# zARv2mNewjazu)sMaSv6JkvX`4!9EOL^uW5}Mz`4n00?tVtdb<_wD*TJ6e$KZ6oam} z2R6|IcXAhoks;8mI%uWm9F)B?sFIB8$0uxl0n^cK^iSBq^b1-!UqEL69Ev2Pl+MDs zJPXH85Q9^bjF1+ztGNvnQjf6sTo~V6hk3>UPS?rE`~|JcWW@Z_G4um{Ek73KoOD2| z6pDzBF2Le*f%gk7bs8=1$q_<`)=aaBo~C9RO_8H6r)jw-FA5FalWJ&oU)9kC=bGK<00000NkvXX Hu0mjf#u}Gq literal 0 HcmV?d00001 diff --git a/docs/img/puml_instantiation.png b/docs/img/puml_instantiation.png new file mode 100644 index 0000000000000000000000000000000000000000..03616a329cce875c0a364fd429f1f61b25360206 GIT binary patch literal 605 zcmV-j0;2tiP)}0|NuYN=9>r@c$=i>e#^o@TRnnm+vw>T)vax(XyQkEIeEc za*=KfE+^+Ra4SgC%YB0qUls)Dcquk)C8IfMlfUTV-AMJs)oi-Y1SioqH00D>&G#J3u_dJ!@JQ`@kfWJR}F+AIHgyGThT@25+ r9c2jlewdnW8?=C;Ktl#2X*>-8vJ>j#`h($q00000NkvXXu0mjf>fsFM literal 0 HcmV?d00001 diff --git a/docs/img/puml_nested.png b/docs/img/puml_nested.png new file mode 100644 index 0000000000000000000000000000000000000000..8b46286dc867880e9a2d397c0acb39e944969b5f GIT binary patch literal 725 zcmV;`0xJE9P)zq{tp{r%6oV!GQ7RLKV4GpB&4*;uJ+v#kk+qb9(}Pr+SKQX-?sA{EA78%k<#6t~ zoFgM5LY|~yvK=5-kuQAw`0@=CcOD_~;5lZ-!-!8svA#%!4cvAV9yx&0(}y81SeLD= zlHzyAP4*6;kE_G<&?q>Y6^4;+0Dxhn8=TFG>7h~dadnvN9mrZ(NkK&9Z*!2FHB-zJ zpoKW0Tl9{30_0}RLBK}=CBBI%7jNGi5!uOx8Mn1`chg)iv zblNY(3P&{Gd9JNS`aToSWHw2|D61==(5jRAycJqClzJ^D9PSJa5b4A0IAu)9SaPfe z5!Yav^ zJ4Cge%_p(%`gu{!-+CKkmv4z`dt1+<{8GKB_NMtJ0_{Dbnx?}J&Sp){_ci=+*#WrR z&w+?29^uKg&6tU~n-ehnpii{YDi0mGISXgcj{df{hO`bw~kCiGV| ztk`*iH;DeK2C$7L6dygfN)e@rT&34SrPrdMtO&1ao1omULCNt$*rb`?CgM|3eDVbm zy88tDOCK~hnow*pWI1;BkrDm50O#*