1 // 2 // Copyright (c) 2015-2016 Vinnie Falco (vinnie dot falco at gmail dot com) 3 // 4 // Distributed under the Boost Software License, Version 1.0. (See accompanying 5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 // 7 8 #ifndef EXAMPLE_HPP 9 #define EXAMPLE_HPP 10 11 #include <cstddef> 12 #include <string> 13 14 // This is a sample header file to show docca XLST results 15 // 16 // namespace, enum, type alias, global, static global, 17 // function, static function, struct/class 18 19 namespace example { 20 21 /** Enum 22 23 Description 24 */ 25 enum enum_t 26 { 27 /// 0 28 zero, 29 30 /// 1 31 one, 32 33 /// 2 34 two 35 }; 36 37 /** Enum class 38 39 Description 40 */ 41 enum class enum_c 42 { 43 /// aaa 44 aaa, 45 46 /// bbb 47 bbb, 48 49 /// ccc 50 ccc 51 }; 52 53 /** Type alias 54 55 Description 56 */ 57 using type = std::string; 58 59 /** Template type alias 60 61 Description 62 */ 63 template<class T> 64 using t_type = std::vector<T>; 65 66 /** Void or deduced 67 68 Description 69 */ 70 using vod = __deduced__; 71 72 /** See below 73 74 Description 75 */ 76 using sb = __see_below__; 77 78 /** Implementation-defined 79 80 Description 81 */ 82 using impdef = __implementation_defined__; 83 84 /** Variable 85 86 Description 87 */ 88 extern std::size_t var; 89 90 /** Static variable 91 92 Description 93 */ 94 static std::size_t s_var = 0; 95 96 /** Brief with @b bold text. 97 98 Function returning @ref type. 99 100 @return The type 101 102 @see t_func. 103 104 @throw std::exception on error 105 @throw std::domain_error on bad parameters 106 107 @par Thread Safety 108 109 Cannot be called concurrently. 110 111 @note Additional notes. 112 113 @param arg1 Function parameter 1 114 @param arg2 Function parameter 2 115 */ 116 type 117 func(int arg1, std::string arg2); 118 119 /** Brief for function starting with _ 120 121 @return @ref type 122 123 @see func 124 */ 125 type 126 _func(float arg1, std::size arg2); 127 128 /** Brief. 129 130 Function description. 131 132 See @ref func. 133 134 @tparam T Template parameter 1 135 @tparam U Template parameter 2 136 @tparam V Template parameter 3 137 138 @param t Function parameter 1 139 @param u Function parameter 2 140 @param v Function parameter 3 141 142 @return nothing 143 */ 144 template<class T, class U> 145 void 146 t_func(T t, U const& u, V&& v); 147 148 /** Overloaded function 1 149 150 Description 151 152 @param arg1 Parameter 1 153 */ 154 void 155 overload(int arg1); 156 157 /** Overloaded function 2 158 159 Description 160 161 @param arg1 Parameter 1 162 @param arg2 Parameter 2 163 */ 164 void 165 overload(int arg1, int arg2); 166 167 /** Overloaded function 3 168 169 Description 170 171 @param arg1 Parameter 1 172 @param arg2 Parameter 2 173 @param arg3 Parameter 3 174 */ 175 void 176 overload(int arg1, int arg2, int arg3); 177 178 /** Markdown examples 179 180 @par List 181 182 1. Lists with extra long lines that can *span* multiple lines 183 and overflow even the longest of buffers. 184 2. With Numbers 185 + Or not 186 + Nesting 187 1. Deeply 188 + And returning `here`. 189 190 Another list I enjoy: 191 192 -# 1 193 - 1.a 194 -# 1.a.1 195 -# 1.a.2 196 - 1.b 197 -# 2 198 - 2.a 199 - 2.b 200 -# 2.b.1 201 -# 2.b.2 202 - 2.b.2.a 203 - 2.b.2.b 204 205 @par Table 206 207 First Header | Second Header 208 ------------- | ------------- 209 Content Cell | Content Cell 210 Content Cell | Content Cell 211 */ 212 void markdown(); 213 214 //------------------------------------------------------------------------------ 215 216 namespace detail { 217 218 /** Detail class 219 220 Description 221 */ 222 struct detail_type 223 { 224 }; 225 226 /** Detail function 227 228 Description 229 */ 230 void 231 detail_function(); 232 233 } // detail 234 235 //------------------------------------------------------------------------------ 236 237 /// Nested namespace 238 namespace nested { 239 240 /** Enum 241 242 Description 243 */ 244 enum enum_t 245 { 246 /// 0 247 zero, 248 249 /// 1 250 one, 251 252 /// 2 253 two 254 }; 255 256 /** Enum class 257 258 Description 259 */ 260 enum class enum_c 261 { 262 /// aaa 263 aaa, 264 265 /// bbb 266 bbb, 267 268 /// ccc 269 ccc 270 }; 271 272 /** Type alias 273 274 Description 275 */ 276 using type = std::string; 277 278 /** Template type alias 279 280 Description 281 */ 282 template<class T> 283 using t_type = std::vector<T>; 284 285 /** Variable 286 287 Description 288 */ 289 extern std::size_t var; 290 291 /** Static variable 292 293 Description 294 */ 295 static std::size_t s_var = 0; 296 297 /** Brief with @b bold text. 298 299 Function returning @ref type. 300 301 @return The type 302 303 @see t_func. 304 305 @throw std::exception on error 306 @throw std::domain_error on bad parameters 307 308 @par Thread Safety 309 310 Cannot be called concurrently. 311 312 @note Additional notes. 313 314 @param arg1 Function parameter 1 315 @param arg2 Function parameter 2 316 */ 317 type 318 func(int arg1, std::string arg2); 319 320 /** Brief for function starting with _ 321 322 @return @ref type 323 324 @see func 325 */ 326 type 327 _func(float arg1, std::size arg2); 328 329 /** Brief. 330 331 Function description. 332 333 See @ref func. 334 335 @tparam T Template parameter 1 336 @tparam U Template parameter 2 337 @tparam V Template parameter 3 338 339 @param t Function parameter 1 340 @param u Function parameter 2 341 @param v Function parameter 3 342 343 @return nothing 344 */ 345 template<class T, class U> 346 void 347 t_func(T t, U const& u, V&& v); 348 349 /** Overloaded function 1 350 351 Description 352 353 @param arg1 Parameter 1 354 */ 355 void 356 overload(int arg1); 357 358 /** Overloaded function 2 359 360 Description 361 362 @param arg1 Parameter 1 363 @param arg2 Parameter 2 364 */ 365 void 366 overload(int arg1, int arg2); 367 368 /** Overloaded function 3 369 370 Description 371 372 @param arg1 Parameter 1 373 @param arg2 Parameter 2 374 @param arg3 Parameter 3 375 */ 376 void 377 overload(int arg1, int arg2, int arg3); 378 379 } // nested 380 381 /// Overloads operators 382 struct Num 383 { 384 385 /// Addition 386 friend 387 Num 388 operator +(Num, Num); 389 390 /// Subtraction 391 friend 392 Num 393 operator -(Num, Num); 394 395 /// Multiplication 396 friend 397 Num 398 operator *(Num, Num); 399 400 /// Division 401 friend 402 Num 403 operator /(Num, Num); 404 405 }; 406 407 /// @ref Num addition 408 Num 409 operator +(Num, Num); 410 411 /// @ref Num subtraction 412 Num 413 operator -(Num, Num); 414 415 /// @ref Num multiplication 416 Num 417 operator *(Num, Num); 418 419 /// @ref Num division 420 Num 421 operator /(Num, Num); 422 423 /** Template class type. 424 425 Description. 426 427 @tparam T Template parameter 1 428 @tparam U Template parameter 2 429 */ 430 template<class T, class U> 431 class class_type 432 { 433 public: 434 /** Enum 435 436 Description 437 */ 438 enum enum_t 439 { 440 /// 0 441 zero, 442 443 /// 1 444 one, 445 446 /// 2 447 two, 448 449 /// _3 450 _three 451 }; 452 453 /** Enum class 454 455 Description 456 */ 457 enum class enum_c 458 { 459 /// aaa 460 aaa, 461 462 /// bbb 463 bbb, 464 465 /// ccc 466 ccc, 467 468 /// _ddd 469 _ddd 470 }; 471 472 /** Type alias 473 474 Description 475 */ 476 using type = std::string; 477 478 /** Template type alias 479 480 Description 481 */ 482 template<class T> 483 using t_type = std::vector<T>; 484 485 /** Variable 486 487 Description 488 */ 489 extern std::size_t var; 490 491 /** Static variable 492 493 Description 494 */ 495 static std::size_t s_var = 0; 496 497 /** Default Ctor 498 499 Description 500 */ 501 class_type(); 502 503 /** Dtor 504 505 Description 506 */ 507 ~class_type(); 508 509 /** Brief with @b bold text. 510 511 Function returning @ref type. 512 513 @return The type 514 515 @see t_func. 516 517 @throw std::exception on error 518 @throw std::domain_error on bad parameters 519 520 @par Thread Safety 521 522 Cannot be called concurrently. 523 524 @note Additional notes. 525 526 @param arg1 Function parameter 1 527 @param arg2 Function parameter 2 528 */ 529 type 530 func(int arg1, std::string arg2); 531 532 /** Brief. 533 534 Function description. 535 536 See @ref func. 537 538 @tparam T Template parameter 1 539 @tparam U Template parameter 2 540 @tparam V Template parameter 3 541 542 @param t Function parameter 1 543 @param u Function parameter 2 544 @param v Function parameter 3 545 546 @return nothing 547 */ 548 template<class T, class U> 549 void 550 t_func(T t, U const& u, V&& v); 551 552 /** Overloaded function 1 553 554 Description 555 556 @param arg1 Parameter 1 557 */ 558 void 559 overload(int arg1); 560 561 /** Overloaded function 2 562 563 Description 564 565 @param arg1 Parameter 1 566 @param arg2 Parameter 2 567 */ 568 void 569 overload(int arg1, int arg2); 570 571 /** Overloaded function 3 572 573 Description 574 575 @param arg1 Parameter 1 576 @param arg2 Parameter 2 577 @param arg3 Parameter 3 578 */ 579 void 580 overload(int arg1, int arg2, int arg3); 581 582 /** Less-than operator 583 584 Description 585 */ 586 bool 587 operator< (class_type const& rhs) const; 588 589 /** Greater-than operator 590 591 Description 592 */ 593 bool 594 operator> (class_type const& rhs) const; 595 596 /** Less-than-or-equal-to operator 597 598 Description 599 */ 600 bool 601 operator<= (class_type const& rhs) const; 602 603 /** Greater-than-or-equal-to operator 604 605 Description 606 */ 607 bool 608 operator>= (class_type const& rhs) const; 609 610 /** Equality operator 611 612 Description 613 */ 614 bool 615 operator== (class_type const& rhs) const; 616 617 /** Inequality operator 618 619 Description 620 */ 621 bool 622 operator!= (class_type const& rhs) const; 623 624 /** Arrow operator 625 626 Description 627 */ 628 std::size_t operator->() const; 629 630 /** Index operator 631 632 Description 633 */ 634 enum_c& operator[](std::size_t); 635 636 /** Index operator 637 638 Description 639 */ 640 enum_c operator[](std::size_t) const; 641 642 /// Public data 643 std::size_t pub_data_; 644 645 /// Public static data 646 static std::size_t pub_sdata_; 647 648 protected: 649 /** Protected data 650 651 Description 652 */ 653 std::size_t prot_data_; 654 655 /** Protected enum 656 657 Description 658 */ 659 enum_c _prot_enum; 660 661 /** Static protected data 662 663 Description 664 */ 665 static std::size_t prot_sdata_; 666 667 /** Protected type 668 669 Description 670 */ 671 struct prot_type 672 { 673 }; 674 675 /** Protected function 676 677 Description 678 */ 679 void prot_memfn(); 680 681 /** Protected function returning @ref prot_type 682 683 Description 684 */ 685 prot_type prot_rvmemfn(); 686 687 /** Protected static member function 688 689 Description 690 */ 691 static void static_prot_memfn(); 692 693 private: 694 /** Private data 695 696 Description 697 */ 698 std::size_t priv_data_; 699 700 /** Static private data 701 702 Description 703 */ 704 static std::size_t priv_sdata_; 705 706 /** Private type 707 708 Description 709 */ 710 struct priv_type 711 { 712 }; 713 714 /** Private function 715 716 Description 717 */ 718 void priv_memfn(); 719 720 /** Private function returning *ref priv_type 721 722 Description 723 */ 724 priv_type priv_rvmemfn(); 725 726 /** Static private member function 727 728 Description 729 */ 730 static void static_priv_memfn(); 731 732 /** Friend class 733 734 Description 735 */ 736 friend friend_class; 737 }; 738 739 /// Other base class 1 740 class other_base_class1 741 { 742 }; 743 744 /// Other base class 2 745 class other_base_class2 746 { 747 }; 748 749 /** Derived type 750 751 Description 752 */ 753 template<class T, class U> 754 class derived_type : 755 public class_type<T, U>, 756 protected other_base_class1, 757 private other_base_class2 758 { 759 }; 760 761 /** References to all identifiers: 762 763 Description one @ref one 764 765 @par See Also 766 767 @li @ref type 768 769 @li @ref t_type 770 771 @li @ref vod 772 773 @li @ref impdef 774 775 @li @ref var 776 777 @li @ref s_var 778 779 @li @ref func 780 781 @li @ref t_func 782 783 @li @ref overload 784 785 @li @ref nested::enum_t : @ref nested::zero @ref nested::one @ref nested::two 786 787 @li @ref nested::enum_c : nested::enum_c::aaa @ref nested::enum_c::bbb @ref nested::enum_c::ccc 788 789 @li @ref nested::type 790 791 @li @ref nested::t_type 792 793 @li @ref nested::var 794 795 @li @ref nested::s_var 796 797 @li @ref nested::func 798 799 @li @ref nested::t_func 800 801 @li @ref nested::overload 802 803 @li @ref class_type 804 805 @li @ref class_type::enum_t : @ref class_type::zero @ref class_type::one @ref class_type::two @ref class_type::_three 806 807 @li @ref class_type::enum_c : class_type::enum_c::aaa @ref class_type::enum_c::bbb @ref class_type::enum_c::ccc class_type::enum_c::_ddd 808 809 @li @ref class_type::type 810 811 @li @ref class_type::t_type 812 813 @li @ref class_type::var 814 815 @li @ref class_type::s_var 816 817 @li @ref class_type::class_type 818 819 @li @ref class_type::func 820 821 @li @ref class_type::t_func 822 823 @li @ref class_type::overload 824 825 @li @ref class_type::pub_data_ 826 827 @li @ref class_type::pub_sdata_ 828 829 @li @ref class_type::_prot_enum 830 831 @li @ref class_type::prot_type 832 833 @li @ref class_type::priv_type 834 835 @li @ref derived_type 836 837 @li @ref Num 838 839 */ 840 void all_ref(); 841 842 } // example 843 844 namespace other { 845 846 /// other function 847 void func(); 848 849 /// other class 850 struct class_type 851 { 852 }; 853 854 855 } // other 856 857 #endif 858