Discussion: standardize namespace format

[mvriel]

Currently you allow the namespace separator to be selectable and whether the namespace should start with a separator. Would it not be easier for people who create transformers if that were standardized?

The authors of parsing tools can convert the namespace format to the intended format when writing the file

[gossi]

I like it more, if I see a php doc, that a backslash () is used as namespace separator and a dot (.) if I see a javascript doc. Or reverse, it would feel wrong to me, if I see a php doc and a dot is used as namespace separator.

[grncdr]

Why not have the namespace be a JSON list? That way transformers and formatters don't need to parse an arbitrary text string.

edit: After looking at the spec, I see that you're using namespaces as keys in an object. I would suggest nesting them instead:

namespaces: {
  "foo": {
    "description": "Description of the foo namespace (if available)",
    "namespaces": {
      "bar": {
         "description": "Description of the foo.bar namespace (or \foo\bar or whatever)"
      }
    }
  }
}

Then in the documentation for individual functions/classes/whatever use JSON lists for namespaces instead of strings.

[gossi]

Interresting. I immediately used the files as top structure. Another approach. I posted about QNAME in #11.

How would DocTools generate the docspec format? They probably process it file by file and could write out the parsed docblocks. With your approach they need to internally create an abstraction of the to documented code and then write it out once all collected, can be very memory consuming for larger code basis. Well that are just speculations, would be cool if a DocTool developer can provide more information on this.

[grncdr]

The only doctool I really know anything about is Sphinx, and it definitely uses an in memory abstraction of the documented code. It's capable enough to create all the Python standard lib documentation (as well as django and a number of other large python projects etc.) so I'm pretty sure the general technique scales reasonably well.

If we want to simplify the job of parser writers so they can deal with one file at a time, I would recommend create language agnostic docspec merging tools. That way the parsers can operate on one file at a time creating many of the above structure, and a second tool can collect all of output and merge it into one final JSON document for the output formatters to process.