Mirror of forum.nim-lang.org

8809 :: Suppressing non-exported fields in nim doc

• cantanima (orginal) [2022-01-15T06:44:50+01:00] view original

  Is there some way to prevent field b from being documented when using nim doc? Or is this the expected behavior?

  type T* = object
     a*: int
     b:float
  Run

  Likewise, should a be printed by the documentation as a*?

---

• Araq (orginal) [2022-01-15T09:06:24+01:00] view original

  There is currently no way to do that but it would easy to improve the docgen.

---

• cantanima (orginal) [2022-01-15T23:48:51+01:00] view original

  There is currently no way to do that...

  OK, but is the current behavior desirable? Seems to me it's mistaken. Nim doc doesn't ordinarily display non-exported symbols.

  ...but it would easy to improve the docgen.

  "Easy" may be a relative term. :-) Here's what I've figured out:

  • T's fields are stored in a node of kind nkIdentDefs.
  • This node does not support flags; or, at least, it does not have the sym field, the way its parent type does.
  • Instead, the node has children, the first of which will be nkPostfix when the field is exported.

  So the "hack" solution is to add the following lines to renderer.nim.

  ...
      # remove line 616 and insert the following
      if n[i].kind == nkPostfix: gsub(g, n[i][1])
      else: gsub(g, n[i])
  ...
        # insert at the new line 1420, then indent the following three lines
        if n[i][0].kind == nkPostfix: # at line 1420 (first line in the loop of case nkRecList of gsub)
  Run

  ...and for the second I indent the next three lines.

  It would seem better (to me) to check the flags of a nkRecList, but it's not apparent to me that that kind of node has any. Am I missing something?

  If this seems OK, I can create a pull request, but I'd be a little surprised.

  Also, I suppose this would be problematic for people who want to keep the current behavior.

  If I should move this discussion to an issue in GitHub, I can do that, too. (& sorry for the noise here if so)

---

• cantanima (orginal) [2022-01-16T07:03:15+01:00] view original

  Looking further, this seems the easiest way short of modifying compiler types. Another alternative might be to add a boolean field to TIdent that indicates whether the identifier is exported. That would remove the need for the nkPostfix arrangement, as well as make the isVisible procedure in renderer.nim unnecessary. But I figure you probably want that nkPostfix arrangement for reasons related to the macro system.

  Eager to know if there's a more elegant solution!

---

• Araq (orginal) [2022-01-16T11:07:34+01:00] view original

  I would add yet another flag to renderer.nim that is used by the docgen, that leaves out a nkIdentDef within a nkObjectTy that lacks the postfix export marker. I suppose that is the solution that you described too.

---

• cantanima (orginal) [2022-01-16T22:10:05+01:00] view original

  Issue here, related pull request here.

---

• cantanima (orginal) [2022-01-20T09:59:55+01:00] view original

  I have a question about CI tests. The pull request has been updated several times: once due to a bug on my part, the others due to the discovery of places where I have to update various tests &c.

  One issue seems to have existed already when I first checked out the code; I just didn't notice it until CI started. It seems that nimterop has trouble building with master branch a95399143. I'm not quite sure how CI is doing it, but compiling its all.nim source file fails, hence my suspicion.

  Can someone confirm or correct that?

  I don't know if the current PR will pass the remaining tests, but if it has only that error which already existed in master (assuming it did), will the Nim dev team still accept it? Or would I have to wait until that issue was ironed out?

---