From b409ed8b449dfd30886ad05020149751ae44afcd Mon Sep 17 00:00:00 2001 From: Matthias Koefferlein Date: Sun, 11 Jan 2026 01:30:25 +0100 Subject: [PATCH] Include hidden classes in documentation to avoid confusion. --- src/gsi/gsi/gsiClassBase.h | 18 +++++- src/lay/lay/layGSIHelpProvider.cc | 103 +++++++++++++++++++++++++----- 2 files changed, 105 insertions(+), 16 deletions(-) diff --git a/src/gsi/gsi/gsiClassBase.h b/src/gsi/gsi/gsiClassBase.h index 6915c00de..8d0c03d5f 100644 --- a/src/gsi/gsi/gsiClassBase.h +++ b/src/gsi/gsi/gsiClassBase.h @@ -203,13 +203,29 @@ public: } /** - * @brief Iterates all subclasses (end) + * @brief Iterates all child classes (end) */ tl::weak_collection::const_iterator end_child_classes () const { return m_child_classes.end (); } + /** + * @brief Iterates all subclasses (begin) + */ + tl::weak_collection::const_iterator begin_subclasses () const + { + return m_subclasses.begin (); + } + + /** + * @brief Iterates all subclasses (end) + */ + tl::weak_collection::const_iterator end_subclasses () const + { + return m_subclasses.end (); + } + /** * @brief Iterates all classes present (begin) */ diff --git a/src/lay/lay/layGSIHelpProvider.cc b/src/lay/lay/layGSIHelpProvider.cc index 43cea0feb..6ece8b5da 100644 --- a/src/lay/lay/layGSIHelpProvider.cc +++ b/src/lay/lay/layGSIHelpProvider.cc @@ -993,7 +993,11 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const << "" << std::endl << std::endl; - os << "" << tl::to_string (QObject::tr ("API reference - Class")) << " " << escape_xml (cls) << "" << std::endl; + os << "" << tl::to_string (QObject::tr ("API reference - Class")) << " " << escape_xml (cls); + if (class_doc.hidden) { + os << " " << tl::to_string (QObject::tr ("[internal]")); + } + os << "" << std::endl; os << "module ()) << "\"/>" << std::endl; os << "" << std::endl; @@ -1006,13 +1010,15 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "

" << tl::to_string (QObject::tr ("Description")) << ": " << escape_xml (class_doc.brief_doc) << "

" << std::endl; - std::vector classes; - classes.push_back (real_class (cls_obj)); + const gsi::ClassBase *act_cls_obj = real_class (cls_obj); - const gsi::ClassBase *base = real_class (cls_obj)->base (); + std::vector classes; + classes.push_back (act_cls_obj); + + const gsi::ClassBase *base = act_cls_obj->base (); if (base) { - const gsi::ClassBase *last_cls = real_class (cls_obj); + const gsi::ClassBase *last_cls = act_cls_obj; bool all_collected = false; os << "

" << tl::to_string (QObject::tr ("Class hierarchy")) << ": " << make_qualified_name (cls_obj); @@ -1032,6 +1038,7 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const all_collected = true; } else if (! all_collected) { // class needs to be mixed into the parent + os << " » name ())) << "\">" << escape_xml (base->name ()) << " " << tl::to_string (QObject::tr ("[internal]")) << ""; classes.push_back (base); } @@ -1051,34 +1058,90 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "

" << std::endl; } + // Produce child classes + bool any = false; for (std::vector::const_iterator c = classes.begin (); c != classes.end (); ++c) { + for (tl::weak_collection::const_iterator cc = (*c)->begin_child_classes (); cc != (*c)->end_child_classes (); ++cc) { DocumentationParser &cdoc = cls_documentation (cc.operator-> ()); - if (! cdoc.hidden || ! cdoc.alias.empty ()) { - - if (any) { - os << ", "; - } else { - os << "

" << tl::to_string (QObject::tr ("Sub-classes")) << ": "; - any = true; - } - - os << " ()))) << "\">" << escape_xml (cc->name ()) << ""; + if (any) { + os << ", "; + } else { + os << "

" << tl::to_string (QObject::tr ("Child classes")) << ": "; + any = true; } + os << " ()))) + << "\">" + << escape_xml (cc->name ()); + if (cdoc.hidden && cdoc.alias.empty ()) { + os << " " << tl::to_string (QObject::tr ("[internal]")); + } + os << ""; + } + } if (any) { os << "

" << std::endl; } + // Produce subclasses (parent classes) + + any = false; + + for (tl::weak_collection::const_iterator cc = act_cls_obj->begin_subclasses (); cc != act_cls_obj->end_subclasses (); ++cc) { + + DocumentationParser &cdoc = cls_documentation (cc.operator-> ()); + + if (any) { + os << ", "; + } else { + os << "

" << tl::to_string (QObject::tr ("Subclasses")) << ": "; + any = true; + } + + os << " ()))) + << "\">" + << escape_xml (cc->name ()); + if (cdoc.hidden && cdoc.alias.empty ()) { + os << " " << tl::to_string (QObject::tr ("[internal]")); + } + os << ""; + + } + + if (any) { + os << "

" << std::endl; + } + + // Inserts an index + os << "" << std::endl; + // Produce class doc body + + if (class_doc.hidden && class_doc.alias.empty ()) { + os << "

" + << tl::to_string (QObject::tr ("Note")) + << ": " + << tl::to_string (QObject::tr ( + "This class is an internal class provided for technical reasons - i.e. " + "as a placeholder class for argument binding or as an abstract interface. " + "You should not instantiate objects of this class directly. " + "Instead, use the subclasses listed above. " + "Also see there for more documentation and actual incarnations of this class." + )) + << "

" << std::endl; + } + os << replace_references (class_doc.doc_html (), cls_obj) << std::endl; // collect the methods of the class and their hidden base classes @@ -1116,6 +1179,8 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "" << std::endl; return os.str (); } + + // Produce methods brief descriptions int n = 0; int row = 0; @@ -1190,6 +1255,8 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "" << std::endl; } + // Produce static methods brief descriptions + any = false; n = 0; @@ -1230,6 +1297,8 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "" << std::endl; } + // Produce protected methods brief descriptions + any = false; n = 0; @@ -1272,6 +1341,8 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "" << std::endl; } + // Produce deprecated methods brief descriptions + any = false; n = 0; @@ -1323,6 +1394,8 @@ GSIHelpProvider::produce_class_doc (const std::string &cls) const os << "" << std::endl; } + // Produce method details + n = 0; os << "

" << tl::to_string (QObject::tr ("Detailed description")) << "

" << std::endl;