zeroc-ice 3.7.11 → 3.8.1

data/dist/ice/cpp/src/Slice/DocCommentParser.h

@@ -0,0 +1,61 @@
+// Copyright (c) ZeroC, Inc.
+
+#ifndef DOC_COMMENT_PARSER_H
+#define DOC_COMMENT_PARSER_H
+
+#include "Parser.h"
+
+namespace Slice
+{
+    class DocCommentFormatter
+    {
+    public:
+        /// Gives the formatter a chance to preprocess a comment before it's parsed.
+        /// @param rawComment The raw lines of the doc-comment (as it's written in the Slice file) minus any formatting
+        /// characters like leading '///' and '*' characters or leading whitespace.
+        //
+        // By default we perform no preprocessing.
+        virtual void preprocess(StringList& rawComment);
+
+        /// This function is called by the doc-comment parser to map code-spans (`<rawText>`) into each language's
+        /// syntax.
+        /// @param rawText The raw text contained within the backticks (the backticks are NOT included).
+        /// @return A properly formatted code span in the target language. The doc-comment parser will replace the
+        /// entire "`...`" string with the returned value.
+        //
+        // By default we just re-emit the text with the original number of backticks around it.
+        [[nodiscard]] virtual std::string formatCode(const std::string& rawText);
+
+        /// This function is called by the doc-comment parser to map '@p' tags into each language's syntax.
+        /// @param param The mapped name of the parameter that is being referenced.
+        /// @return A properly formatted parameters reference in the target language. The doc-comment parser will
+        /// replace the entire "@p <rawParamName>" string with the returned value.
+        //
+        // By default we just emit the parameter's name in code formatting.
+        [[nodiscard]] virtual std::string formatParamRef(const std::string& param);
+
+        /// This function is called by the doc-comment parser to map doc-links ('{@link <rawLink>}') into each
+        /// language's syntax.
+        /// @param rawLink The link's raw text, taken verbatim from the doc-comment.
+        /// @param source A pointer to the Slice element that the doc-comment (and link) are written on.
+        /// @param target A pointer to the Slice element that is being linked to, or `nullptr` if it doesn't exist.
+        /// @return A properly formatted doc-link in the target language. The doc-comment parser will replace the
+        /// entire "{@link <rawLink>}" string with the returned value.
+        [[nodiscard]] virtual std::string
+        formatLink(const std::string& rawLink, const ContainedPtr& source, const SyntaxTreeBasePtr& target) = 0;
+
+        /// This function is called by the doc-comment parser to map see-also references ('@see <rawLink>') into each
+        /// language's syntax.
+        /// @param rawLink The references's raw text, taken verbatim from the doc-comment.
+        /// @param source A pointer to the Slice element that the doc-comment (and reference) are written on.
+        /// @param target A pointer to the Slice element that is being referenced, or `nullptr` if it doesn't exist.
+        /// @return A properly formatted see-also-link in the target language. This value will be stored in the
+        /// doc-comment's `seeAlso` field.
+        [[nodiscard]] virtual std::string
+        formatSeeAlso(const std::string& rawLink, const ContainedPtr& source, const SyntaxTreeBasePtr& target);
+    };
+
+    /// Parses all doc-comments within the provided unit (in-place).
+    void parseAllDocComments(const UnitPtr& unit, DocCommentFormatter& formatter);
+}
+#endif

data/dist/ice/cpp/src/Slice/FileTracker.cpp

@@ -1,77 +1,27 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
-#include <Slice/FileTracker.h>
-#include <IceUtil/ConsoleUtil.h>
-#include <IceUtil/FileUtil.h>
+#include "FileTracker.h"
+#include "../Ice/ConsoleUtil.h"
+#include "../Ice/FileUtil.h"
 
-using namespace IceUtilInternal;
-using namespace std;
-
-Slice::FileException::FileException(const char* file, int line, const string& r) :
-    IceUtil::Exception(file, line),
-    _reason(r)
-{
-}
-
-#ifndef ICE_CPP11_COMPILER
-Slice::FileException::~FileException() throw()
-{
-}
-#endif
-
-string
-Slice::FileException::ice_id() const
-{
-    return "::Slice::FileException";
-}
-
-void
-Slice::FileException::ice_print(ostream& out) const
-{
-    IceUtil::Exception::ice_print(out);
-    out << ": " << _reason;
-}
+#include <cassert>
 
-#ifndef ICE_CPP11_MAPPING
-Slice::FileException*
-Slice::FileException::ice_clone() const
-{
-    return new FileException(*this);
-}
-#endif
-
-void
-Slice::FileException::ice_throw() const
-{
-    throw *this;
-}
-
-string
-Slice::FileException::reason() const
-{
-    return _reason;
-}
+using namespace IceInternal;
+using namespace std;
 
 static Slice::FileTrackerPtr Instance;
 
-Slice::FileTracker::FileTracker() :
-    _curr(_generated.end())
-{
-}
+Slice::FileTracker::FileTracker() : _curr(_generated.end()) {}
 
-Slice::FileTracker::~FileTracker()
-{
-}
+Slice::FileTracker::~FileTracker() = default;
 
 // The file tracker is not supposed to be thread safe.
 Slice::FileTrackerPtr
 Slice::FileTracker::instance()
 {
-    if(!Instance)
+    if (!Instance)
     {
-        Instance = new FileTracker();
+        Instance = make_shared<FileTracker>();
     }
     return Instance;
 }
@@ -80,7 +30,7 @@ void
 Slice::FileTracker::setSource(const string& source)
 {
     _source = source;
-    pair<map<string, list<string> >::iterator, bool> p = _generated.insert(make_pair(source, list<string>()));
+    pair<map<string, list<string>>::iterator, bool> p = _generated.insert(make_pair(source, list<string>()));
     assert(p.second);
     _curr = p.first;
 }
@@ -96,8 +46,8 @@ Slice::FileTracker::error()
 void
 Slice::FileTracker::addFile(const string& file)
 {
-    _files.push_front(make_pair(file, false));
-    if(_curr != _generated.end())
+    _files.emplace_front(file, false);
+    if (_curr != _generated.end())
     {
         _curr->second.push_back(file);
     }
@@ -106,21 +56,21 @@ Slice::FileTracker::addFile(const string& file)
 void
 Slice::FileTracker::addDirectory(const string& dir)
 {
-    _files.push_front(make_pair(dir, true));
+    _files.emplace_front(dir, true);
 }
 
 void
 Slice::FileTracker::cleanup()
 {
-    for(list<pair<string, bool> >::const_iterator p = _files.begin(); p != _files.end(); ++p)
+    for (const auto& file : _files)
     {
-        if(!p->second)
+        if (!file.second)
         {
-            IceUtilInternal::unlink(p->first);
+            IceInternal::unlink(file.first);
         }
         else
         {
-            IceUtilInternal::rmdir(p->first);
+            IceInternal::rmdir(file.first);
         }
     }
 }
@@ -128,16 +78,16 @@ Slice::FileTracker::cleanup()
 void
 Slice::FileTracker::dumpxml()
 {
-    consoleOut << "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" << endl;
+    consoleOut << R"(<?xml version="1.0" encoding="UTF-8"?>)" << endl;
     consoleOut << "<generated>";
-    for(map<string, list<string> >::const_iterator p = _generated.begin(); p != _generated.end(); ++p)
+    for (const auto& p : _generated)
     {
-        if(!p->second.empty())
+        if (!p.second.empty())
         {
-            consoleOut << endl << "  <source name=\"" << p->first << "\">";
-            for(list<string>::const_iterator q = p->second.begin(); q != p->second.end(); ++q)
+            consoleOut << endl << "  <source name=\"" << p.first << "\">";
+            for (const auto& q : p.second)
             {
-                consoleOut << endl << "    <file name=\"" << *q << "\"/>";
+                consoleOut << endl << "    <file name=\"" << q << "\"/>";
             }
             consoleOut << endl << "  </source>";
         }

data/dist/ice/cpp/src/Slice/FileTracker.h

@@ -1,66 +1,45 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
 #ifndef FILE_TRACKER_H
 #define FILE_TRACKER_H
 
-#include <IceUtil/Shared.h>
-#include <Slice/Parser.h>
+#include <list>
+#include <map>
+#include <memory>
+#include <stdexcept>
+#include <string>
 
 namespace Slice
 {
-
-class FileException : public ::IceUtil::Exception
-{
-public:
-
-    FileException(const char*, int, const std::string&);
-#ifndef ICE_CPP11_COMPILER
-    ~FileException() throw();
-#endif
-    virtual std::string ice_id() const;
-    virtual void ice_print(std::ostream&) const;
-#ifndef ICE_CPP11_MAPPING
-    virtual FileException* ice_clone() const;
-#endif
-    virtual void ice_throw() const;
-
-    std::string reason() const;
-
-private:
-
-    static const char* _name;
-    const std::string _reason;
-};
-
-class FileTracker;
-typedef IceUtil::Handle<FileTracker> FileTrackerPtr;
-
-class FileTracker : public ::IceUtil::SimpleShared
-{
-public:
-
-    FileTracker();
-    ~FileTracker();
-
-    static FileTrackerPtr instance();
-
-    void setSource(const std::string&);
-    void addFile(const std::string&);
-    void addDirectory(const std::string&);
-    void error();
-    void cleanup();
-    void dumpxml();
-
-private:
-
-    std::list<std::pair< std::string, bool> > _files;
-    std::string _source;
-    std::map<std::string, std::list<std::string> > _generated;
-    std::map<std::string, std::list<std::string> >::iterator _curr;
-};
-
+    class FileException final : public std::runtime_error
+    {
+    public:
+        using std::runtime_error::runtime_error;
+    };
+
+    class FileTracker;
+    using FileTrackerPtr = std::shared_ptr<FileTracker>;
+    class FileTracker final
+    {
+    public:
+        FileTracker();
+        ~FileTracker();
+
+        static FileTrackerPtr instance();
+
+        void setSource(const std::string& source);
+        void addFile(const std::string& file);
+        void addDirectory(const std::string& dir);
+        void error();
+        void cleanup();
+        void dumpxml();
+
+    private:
+        std::list<std::pair<std::string, bool>> _files;
+        std::string _source;
+        std::map<std::string, std::list<std::string>> _generated;
+        std::map<std::string, std::list<std::string>>::iterator _curr;
+    };
 }
 
 #endif