Skip to content

Format see also in Python & Swift #4622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Nov 4, 2025
Merged

Format see also in Python & Swift #4622

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
96fea82
Format see also in Python & Swift
pepone Nov 3, 2025
f8f2c6e
Remove TODO comment
pepone Nov 3, 2025
86db31e
Update cpp/src/slice2py/PythonUtil.cpp
pepone Nov 3, 2025
4ba92f6
Update cpp/src/slice2py/PythonUtil.cpp
pepone Nov 3, 2025
3e4a286
Update cpp/src/slice2swift/SwiftUtil.cpp
pepone Nov 3, 2025
e7e48f4
Review fixes
pepone Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 50 additions & 12 deletions cpp/src/slice2py/PythonUtil.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,11 @@ class PythonDocCommentFormatter final : public DocCommentFormatter
{
return Slice::Python::pyLinkFormatter(rawLink, source, target);
}

string formatSeeAlso(const string& rawLink, const ContainedPtr& source, const SyntaxTreeBasePtr& target) final
{
return Slice::Python::pyLinkFormatter(rawLink, source, target);
}
Copy link
Member

@InsertCreativityHere InsertCreativityHere Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't necessary, formatSeeAlso is default-implemented to call formatLink:

ice/cpp/src/Slice/DocCommentParser.cpp

Lines 68 to 73 in daaa6e3

string
DocCommentFormatter::formatSeeAlso(const string& rawLink, const ContainedPtr& source, const SyntaxTreeBasePtr& target)
{
// Many languages don't support 'see-also' tags, so by default we map them to regular doc-links.
return formatLink(rawLink, source, target);
}

and indeed, this has the same implementation as formatLink.

};

string
Expand Down Expand Up @@ -2257,6 +2262,25 @@ Slice::Python::CodeVisitor::writeRemarksDocComment(const StringList& remarks, bo
}
}

void
Slice::Python::CodeVisitor::writeSeeAlso(const StringList& seeAlso, bool needsNewline, Output& out)
{
if (!seeAlso.empty())
{
if (needsNewline)
{
out << nl;
}

out << nl << "See Also";
out << nl << "--------";
for (const string& line : seeAlso)
{
out << nl << line;
}
}
}

void
Slice::Python::CodeVisitor::writeDocstring(const optional<DocComment>& comment, const string& prefix, Output& out)
{
Expand Down Expand Up @@ -2310,7 +2334,8 @@ Slice::Python::CodeVisitor::writeDocstring(

const StringList& overview = comment->overview();
const StringList& remarks = comment->remarks();
if (overview.empty() && remarks.empty() && docs.empty())
const StringList& seeAlso = comment->seeAlso();
if (overview.empty() && remarks.empty() && docs.empty() && seeAlso.empty())
{
return;
}
Expand Down Expand Up @@ -2352,6 +2377,8 @@ Slice::Python::CodeVisitor::writeDocstring(

writeRemarksDocComment(remarks, !overview.empty() || !docs.empty(), out);

writeSeeAlso(seeAlso, !overview.empty() || !docs.empty() || !remarks.empty(), out);

out << nl << tripleQuotes;
}

Expand Down Expand Up @@ -2380,7 +2407,8 @@ Slice::Python::CodeVisitor::writeDocstring(const optional<DocComment>& comment,

const StringList& overview = comment->overview();
const StringList& remarks = comment->remarks();
if (overview.empty() && remarks.empty() && docs.empty())
const StringList& seeAlso = comment->seeAlso();
if (overview.empty() && remarks.empty() && docs.empty() && seeAlso.empty())
{
return;
}
Expand Down Expand Up @@ -2417,6 +2445,8 @@ Slice::Python::CodeVisitor::writeDocstring(const optional<DocComment>& comment,

writeRemarksDocComment(remarks, !overview.empty() || !docs.empty(), out);

writeSeeAlso(seeAlso, !overview.empty() || !docs.empty() || !remarks.empty(), out);

out << nl << tripleQuotes;
}

Expand All @@ -2438,11 +2468,12 @@ Slice::Python::CodeVisitor::writeDocstring(const OperationPtr& op, MethodKind me

const StringList& overview = comment->overview();
const StringList& remarks = comment->remarks();
const StringList& seeAlso = comment->seeAlso();
const StringList& returnsDoc = comment->returns();
const auto& parametersDoc = comment->parameters();
const auto& exceptionsDoc = comment->exceptions();

if (overview.empty() && remarks.empty())
if (overview.empty() && remarks.empty() && seeAlso.empty())
{
if ((methodKind == MethodKind::SyncInvocation || methodKind == MethodKind::Dispatch) && parametersDoc.empty() &&
exceptionsDoc.empty() && returnsDoc.empty())
Expand Down Expand Up @@ -2636,6 +2667,7 @@ Slice::Python::CodeVisitor::writeDocstring(const OperationPtr& op, MethodKind me
}

writeRemarksDocComment(remarks, true, out);
writeSeeAlso(seeAlso, true, out);

out << nl << tripleQuotes;
}
Expand Down Expand Up @@ -3004,19 +3036,25 @@ Slice::Python::pyLinkFormatter(const string& rawLink, const ContainedPtr&, const
{
result << "``";

auto hashPos = rawLink.find('#');
if (hashPos != string::npos)
// Replace "::"" by "." in the raw link. This is for the situation where the user passes a Slice type
// reference but (a) the source Slice file does not include this type and (b) there is no python:identifier or
// other identifier renaming.
string targetS = rawLink;
// Replace any "::" scope separators with '.'s.
auto pos = targetS.find("::");
while (pos != string::npos)
{
if (hashPos != 0)
{
result << rawLink.substr(0, hashPos) << ".";
}
result << rawLink.substr(hashPos + 1);
targetS.replace(pos, 2, ".");
pos = targetS.find("::", pos);
}
else
// Replace any '#' scope separators with '.'s.
replace(targetS.begin(), targetS.end(), '#', '.');
// Remove any leading scope separators.
if (targetS.find('.') == 0)
{
result << rawLink;
targetS.erase(0, 1);
}
result << targetS;

result << "``";
}
Expand Down
3 changes: 3 additions & 0 deletions cpp/src/slice2py/PythonUtil.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -453,6 +453,9 @@ namespace Slice::Python
/// Writes the provided @p remarks in its own subheading in the current comment (if @p remarks is non-empty).
void writeRemarksDocComment(const StringList& remarks, bool needsNewline, IceInternal::Output& out);

/// Writes the provided @p seeAlso in its own subheading in the current comment (if @p seeAlso is non-empty).
void writeSeeAlso(const StringList& seeAlso, bool needsNewline, IceInternal::Output& out);

void writeDocstring(const std::optional<DocComment>&, const std::string&, IceInternal::Output&);
void writeDocstring(const std::optional<DocComment>&, const DataMemberList&, IceInternal::Output&);
void writeDocstring(const std::optional<DocComment>&, const EnumPtr&, IceInternal::Output&);
Expand Down
5 changes: 5 additions & 0 deletions cpp/src/slice2swift/Main.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ class SwiftDocCommentFormatter final : public DocCommentFormatter
{
return Slice::Swift::swiftLinkFormatter(rawLink, source, target);
}

string formatSeeAlso(const string& rawLink, const ContainedPtr& source, const SyntaxTreeBasePtr& target) final
{
return Slice::Swift::swiftLinkFormatter(rawLink, source, target);
}
Copy link
Member

@InsertCreativityHere InsertCreativityHere Nov 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also not necessary, will already re-use formatLink automatically.

};

static void
Expand Down
15 changes: 12 additions & 3 deletions cpp/src/slice2swift/SwiftUtil.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,18 +105,27 @@ Slice::Swift::writeDocSummary(IceInternal::Output& out, const ContainedPtr& p)
hasStarted = true;
}

// TODO we should add a section for '@see' tags.

const StringList& remarks = doc->remarks();
if (!remarks.empty())
{
if (hasStarted)
{
out << nl << "///";
}
out << nl << "/// ## Remarks";
out << nl << "/// - Remark:";
writeDocLines(out, remarks);
}

const StringList& seeAlso = doc->seeAlso();
if (!seeAlso.empty())
{
if (hasStarted)
{
out << nl << "///";
}
out << nl << "/// - See Also";
writeDocLines(out, seeAlso);
}
}

void
Expand Down
Loading