)]}'
{
  "commit": "a942d572073e98944200e154597442796fdb13de",
  "tree": "b00debc75c2553f74fbe4a1be9aa11c321a34b19",
  "parents": [
    "3599db2e40df28f0f1335f5f00dd2bf0e5d2684a"
  ],
  "author": {
    "name": "David Benjamin",
    "email": "davidben@google.com",
    "time": "Thu Dec 14 14:27:27 2023 -0500"
  },
  "committer": {
    "name": "Boringssl LUCI CQ",
    "email": "boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com",
    "time": "Mon Dec 18 18:59:54 2023 +0000"
  },
  "message": "Support lists and code blocks in doc.go\n\nOur documentation comments already include examples of code blocks\nand lists, they just don\u0027t get rendered right. We also have things that\nwere trying to be lists but aren\u0027t. Go ahead and add support for it, and\nfix the handful of list-like things that didn\u0027t get rendered as lists.\n\nI took inspiration from CommonMark (https://spec.commonmark.org/0.30/)\nto resolve questions such as whether blank lines are needed between\nlists, etc., but this does not support any kind of nesting and is still\nfar from a CommonMark parser. Aligning with CommonMark leaves the door\nopen to pulling in a real Markdown parser if we start to need too many\nfeatures. I\u0027ve also borrowed the \"block\" terminology from CommonMark.\n\nOne ambiguity of note: whether lists may interrupt paragraphs (i.e.\nwithout a blank line in between) is a little thorny. If we say no, this\ndoesn\u0027t work:\n\n   Callers should heed the following warnings:\n   1) Don\u0027t use the function\n   2) Seriously, don\u0027t use this function\n   3) This function is a bad idea\n\nBut if we say yes, this renders wrong:\n\n   This function parses an X.509 certificate (see RFC\n   5280) into an X509 object.\n\nWe have examples of both in existing comments, though we could easily\nadd a blank line in the former or rewrap the latter. CommonMark has a\ndiscussion on this in https://spec.commonmark.org/0.30/#lists\n\nCommonMark says yes, but with a hack that only lists starting with 1 can\ninterrupt paragraphs. Since we\u0027re unlikely to cite RFC 1, I\u0027ve matched\nfor now, but we may want to revisit this if it gets to be a pain. I\ncould imagine this becoming a problem:\n\n   This function, on success, does some stuff and returns\n   1. Otherwise, it returns 0.\n\nBut that looks a little weird and we usually spell out \"one\" and \"zero\".\nI printed all the lists we detected in existing comments, and this has\nnot happened so far.\n\nI\u0027ve also required fewer spaces than CommonMark to trigger a code block.\nCommonMark uses four, but four spaces plus a leading \"//\" and a \" \" is\nquite a lot. For now I\u0027m not stripping the spaces after the comment\nmarker at comment extraction time and then requiring three spaces, so\ntwo spaces relative to normal text. This is mostly to match what we\u0027ve\ncurrently been doing, but we can always change it and our comments\nlater.\n\nChange-Id: Ic61a8e93491ed96aba755aec2a5f32914bdc42ae\nReviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/64930\nReviewed-by: Bob Beck \u003cbbe@google.com\u003e\nCommit-Queue: David Benjamin \u003cdavidben@google.com\u003e\n",
  "tree_diff": [
    {
      "type": "modify",
      "old_id": "92ff7a140ac479aedfbe52cec781c366f6522dfa",
      "old_mode": 33188,
      "old_path": "include/openssl/bn.h",
      "new_id": "fb6e96259a82d02e1942bfa2f7f5050e81040959",
      "new_mode": 33188,
      "new_path": "include/openssl/bn.h"
    },
    {
      "type": "modify",
      "old_id": "a455389c1aeaa06ca91488d15d89450f82dcc018",
      "old_mode": 33188,
      "old_path": "include/openssl/curve25519.h",
      "new_id": "b87df52789eff6cf17d40b4e5a2820eb45f81515",
      "new_mode": 33188,
      "new_path": "include/openssl/curve25519.h"
    },
    {
      "type": "modify",
      "old_id": "2d005af6c3ae648bc3964da3d30a76733286aaf9",
      "old_mode": 33188,
      "old_path": "include/openssl/ec.h",
      "new_id": "e8a2db0a07fe3317dd32b4ae64cb747cfcab6028",
      "new_mode": 33188,
      "new_path": "include/openssl/ec.h"
    },
    {
      "type": "modify",
      "old_id": "ab6225e9e61aa9096c62b5608d0655b18cf7ee1f",
      "old_mode": 33188,
      "old_path": "include/openssl/ssl.h",
      "new_id": "ff4d4c91c331ecc5b1291b422ac61d9ca1867a49",
      "new_mode": 33188,
      "new_path": "include/openssl/ssl.h"
    },
    {
      "type": "modify",
      "old_id": "a868e4444578088a0b7b75f90ab252c96389b0d1",
      "old_mode": 33188,
      "old_path": "util/doc.css",
      "new_id": "f176f259b787e9f889555f3e8d81a0fb5edf3225",
      "new_mode": 33188,
      "new_path": "util/doc.css"
    },
    {
      "type": "modify",
      "old_id": "ae5c45df8b505b284cd77b864113ac316ed72a14",
      "old_mode": 33188,
      "old_path": "util/doc.go",
      "new_id": "21d9dab1fcd7338e35fac0136c5dfdade4a5cf7a",
      "new_mode": 33188,
      "new_path": "util/doc.go"
    }
  ]
}