Lint to check references in DocComments
This looks through @return and @param references and ensures they exist.
Bug: 132905850
Test: HidlLintTest.DocCommentRefTest (./test/run_all_host_tests.sh)
Change-Id: I13491581f6b31dc15c225af3d02628640da5a525
diff --git a/generateCpp.cpp b/generateCpp.cpp
index 597a227..1c1ff88 100644
--- a/generateCpp.cpp
+++ b/generateCpp.cpp
@@ -20,6 +20,7 @@
#include "EnumType.h"
#include "HidlTypeAssertion.h"
#include "Interface.h"
+#include "Location.h"
#include "Method.h"
#include "Reference.h"
#include "ScalarType.h"
@@ -107,7 +108,8 @@
"during device boot. If getStub is true, this will try to return an unwrapped\n"
"passthrough implementation in the same process. This is useful when getting an\n"
"implementation from the same partition/compilation group.\n\n"
- "In general, prefer getService(std::string,bool)")
+ "In general, prefer getService(std::string,bool)",
+ HIDL_LOCATION_HERE)
.emit(out);
} else {
DocComment(
@@ -117,24 +119,29 @@
"become available. If the service is a lazy service, this will start the service\n"
"and return when it becomes available. If getStub is true, this will try to\n"
"return an unwrapped passthrough implementation in the same process. This is\n"
- "useful when getting an implementation from the same partition/compilation group.")
+ "useful when getting an implementation from the same partition/compilation group.",
+ HIDL_LOCATION_HERE)
.emit(out);
}
out << "static ::android::sp<" << interfaceName << "> " << functionName << "("
<< "const std::string &serviceName=\"default\", bool getStub=false);\n";
- DocComment("Deprecated. See " + functionName + "(std::string, bool)").emit(out);
+ DocComment("Deprecated. See " + functionName + "(std::string, bool)", HIDL_LOCATION_HERE)
+ .emit(out);
out << "static ::android::sp<" << interfaceName << "> " << functionName << "("
<< "const char serviceName[], bool getStub=false)"
<< " { std::string str(serviceName ? serviceName : \"\");"
<< " return " << functionName << "(str, getStub); }\n";
- DocComment("Deprecated. See " + functionName + "(std::string, bool)").emit(out);
+ DocComment("Deprecated. See " + functionName + "(std::string, bool)", HIDL_LOCATION_HERE)
+ .emit(out);
out << "static ::android::sp<" << interfaceName << "> " << functionName << "("
<< "const ::android::hardware::hidl_string& serviceName, bool getStub=false)"
// without c_str the std::string constructor is ambiguous
<< " { std::string str(serviceName.c_str());"
<< " return " << functionName << "(str, getStub); }\n";
DocComment("Calls " + functionName +
- "(\"default\", bool). This is the recommended instance name for singleton services.")
+ "(\"default\", bool). This is the recommended instance name for singleton "
+ "services.",
+ HIDL_LOCATION_HERE)
.emit(out);
out << "static ::android::sp<" << interfaceName << "> " << functionName << "("
<< "bool getStub) { return " << functionName << "(\"default\", getStub); }\n";
@@ -146,11 +153,13 @@
DocComment(
"Registers a service with the service manager. For Trebilized devices, the service\n"
- "must also be in the VINTF manifest.")
+ "must also be in the VINTF manifest.",
+ HIDL_LOCATION_HERE)
.emit(out);
out << "__attribute__ ((warn_unused_result))"
<< "::android::status_t registerAsService(const std::string &serviceName=\"default\");\n";
- DocComment("Registers for notifications for when a service is registered.").emit(out);
+ DocComment("Registers for notifications for when a service is registered.", HIDL_LOCATION_HERE)
+ .emit(out);
out << "static bool registerForNotifications(\n";
out.indent(2, [&] {
out << "const std::string &serviceName,\n"
@@ -273,11 +282,13 @@
out.indent();
- DocComment("Type tag for use in template logic that indicates this is a 'pure' class.")
+ DocComment("Type tag for use in template logic that indicates this is a 'pure' class.",
+ HIDL_LOCATION_HERE)
.emit(out);
generateCppTag(out, "android::hardware::details::i_tag");
- DocComment("Fully qualified interface name: \"" + iface->fqName().string() + "\"")
+ DocComment("Fully qualified interface name: \"" + iface->fqName().string() + "\"",
+ HIDL_LOCATION_HERE)
.emit(out);
out << "static const char* descriptor;\n\n";
@@ -288,7 +299,8 @@
if (iface) {
DocComment(
- "Returns whether this object's implementation is outside of the current process.")
+ "Returns whether this object's implementation is outside of the current process.",
+ HIDL_LOCATION_HERE)
.emit(out);
out << "virtual bool isRemote() const ";
if (!isIBase()) {
@@ -305,7 +317,7 @@
const NamedReference<Type>* elidedReturn = method->canElideCallback();
if (elidedReturn == nullptr && returnsValue) {
- DocComment("Return callback for " + method->name()).emit(out);
+ DocComment("Return callback for " + method->name(), HIDL_LOCATION_HERE).emit(out);
out << "using "
<< method->name()
<< "_cb = std::function<void(";
@@ -344,7 +356,8 @@
for (const Interface *superType : iface->typeChain()) {
DocComment(
"This performs a checked cast based on what the underlying implementation "
- "actually is.")
+ "actually is.",
+ HIDL_LOCATION_HERE)
.emit(out);
out << "static ::android::hardware::Return<"
<< childTypeResult
@@ -624,7 +637,7 @@
}
void AST::generateTemplatizationLink(Formatter& out) const {
- DocComment("The pure class is what this class wraps.").emit(out);
+ DocComment("The pure class is what this class wraps.", HIDL_LOCATION_HERE).emit(out);
out << "typedef " << mRootScope.getInterface()->localName() << " Pure;\n\n";
}
@@ -685,7 +698,8 @@
out.endl();
generateTemplatizationLink(out);
- DocComment("Type tag for use in template logic that indicates this is a 'native' class.")
+ DocComment("Type tag for use in template logic that indicates this is a 'native' class.",
+ HIDL_LOCATION_HERE)
.emit(out);
generateCppTag(out, "android::hardware::details::bnhw_tag");
@@ -779,7 +793,8 @@
<< "\n\n";
generateTemplatizationLink(out);
- DocComment("Type tag for use in template logic that indicates this is a 'proxy' class.")
+ DocComment("Type tag for use in template logic that indicates this is a 'proxy' class.",
+ HIDL_LOCATION_HERE)
.emit(out);
generateCppTag(out, "android::hardware::details::bphw_tag");