{"id":1480,"date":"2021-11-22T15:19:02","date_gmt":"2021-11-22T21:19:02","guid":{"rendered":"https:\/\/blog.scitools.com\/?p=1480"},"modified":"2023-10-02T09:58:51","modified_gmt":"2023-10-02T15:58:51","slug":"as-built-documentation","status":"publish","type":"post","link":"https:\/\/blog.scitools.com\/as-built-documentation\/","title":{"rendered":"As-Built Documentation"},"content":{"rendered":"\n

Abstract: What does \u201cas-built documentation\u201d mean? For me, it means being able to find answers to my questions by quickly viewing references in the code. Take a look at how I use as-built documentation in a real-life scenario with Understand.<\/p>\n\n\n\n

Most of the time, my internal definition for a given buzzword or catchphrase is: \u201ckeyword to obtain money.\u201d What is STEM?  \u201cA word to use to obtain grant money and\/or donations\u201d What is organic? \u201cA word attached to food that increases the price.\u201d What is \u201cas-built documentation?\u201d “A catchphrase to get you to invest your money in Understand.”<\/p>\n\n\n\n

However, a buzzword or catchphrase is more efficient at obtaining money when it has meaning. What does \u201cas-built documentation\u201d mean? I\u2019m not sure how the sales team defines it, but here\u2019s a use case from my development.<\/p>\n\n\n\n

The Understand strict c++ parser uses the llvm <\/a>library. I needed to modify the strict parser to be able to read files directly from git, not from the disk. The strict parser already provides a virtual file system for the llvm library to handle file encodings, but the status call deferred to the real file system. Because the files exist only in git and not on disk, the real file system can\u2019t find them and the status call results in a file not found error.<\/p>\n\n\n\n

In this scenario, \u201cas-built documentation\u201d means instead of trying to find the official llvm documentation, I looked through the references. Here\u2019s the overload for status that delegates to the real file system (it turns out opening the file for reading also delegates to the real file system).<\/p>\n\n\n\n

  llvm::ErrorOr<llvm::vfs::Status> status(const Twine &path) override\n  {\n    if (mCodec || !mCompiler.isEmpty()) {\n      \/\/ Stat can't be optimized. The file has\n      \/\/ to be opened and converted to UTF-8.\n      if (auto file = openFileForRead(path))\n        return (*file)->status();\n    }\n    return mReal->status(path);\n  }<\/code><\/pre>\n\n\n\n
So, the first step is to see what the status function does. Control-Click updates the information browser and previewer.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
The pure virtual implementation isn\u2019t immediately helpful. But, one of the overrides starts with \u201cRealFileSystem\u201d so double-clicking on that in the information browser gives:<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
It looks like the real file system copies an existing status (line 293). Clicking through the other overloads shows most of them delegate to another file system like our code is already doing. So, the next approach is to look directly at the status class with Control+Click.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
Scrolling down a little reveals three constructors. Since a valid status doesn\u2019t already exist, only the third constructor matters.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
What values should I use for the parameters? Some seem obvious (I know the file name), but I have no idea what the UniqueID is. So, I’ll look through some calls.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
The first call reference is not helpful. It\u2019s essentially a copy. Several more are also copies. One useful call is from the InMemoryFileSystem.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
It looks like this status has essentially default parameters. So, I can start from this and change the parameters I know. I know the filename. I still don’t know what the UniqueId is, but now I know a function to generate one: getNextVirtualUniqueID(). The timestamp of the git commit is known, but what is a TimePoint object? I could click on the TimePoint class to pull up the class, but I\u2019ve glanced through the calls already and know there\u2019s a useful one:<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
I can determine the type of the variable ModificationTime by hovering. I know the time_t for my file so I can just pass it to this conversion function. The next two parameters are user and group, but I don\u2019t know those and it looks valid to leave them null. Then is the size, which I do know, so I can update that. Next is the file type. The git file is a file, not a directory. What are the other enum values? I can control+click on directory_file to find the enumerator definition.<\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
So, I\u2019ll replace the directory_file enumerator with the regular_file enumerator to treat the git files as regular files. I can similarly look up the permissions enumerator by using the back button on the previewer and then Control+click all_all. <\/p>\n\n\n\n
\"\"<\/a><\/figure>\n\n\n\n
I\u2019m not sure if the permissions will matter, but I know writing won\u2019t be supported. So, I\u2019ll update the enumerator to \u201call_read\u201d. Putting it all together, I can construct a status object if the real file system failed to find the file:<\/p>\n\n\n\n
\n
      auto status = mReal->status(path);\n      if (!status && file.IsValid()) {\n        \/\/ file exists virtually, create a status for it\n        status = llvm::vfs::Status(path.str().c_str(),\n                                   llvm::vfs::getNextVirtualUniqueID(),\n                                   llvm::sys::toTimePoint(file.GetTimestamp()),\n                                   0, 0, file.GetSize(),\n                                   llvm::sys::fs::file_type::regular_file,\n                                   llvm::sys::fs::perms::all_read);\n\n      }<\/code><\/pre>\n\n\n\n
<\/p>\n<\/div><\/div>\n\n\n\n
Voila, my git files are found. So, what does \u201cas-built documentation\u201d mean? For me, it means being able to find answers to my questions by quickly viewing references in the code. Hopefully, it\u2019s now a better catchphrase to convince you to invest money in Understand<\/a>.<\/p>\n\n\n\n