For Good Measure

@index and @location tags for documentation generators

by Colby Russell. 2020 May 10.

(I'm including below two entries from my paper journal from 2015.)

2015 March 12

One of the worst parts about trying to introduce yourself to the source of a new project is grappling with the source layout. I think I've struck upon an approach to dealing with this.

I propose two new tags for documentation generators: @location and @index.

@location should be used to explain why a file is where it is. To be used judiciously. (I'm hesitant to say "sparingly", since that's usually taken to mean "don't use this", and that's not what I mean.)

@index can be used to document the source tree layout. We have @fileoverview, but that does little to explain the rationale behind directory structure. Use @index within a single file within a directory to delegate this responsibility to that file. Can be combined with @location or @fileoverview.

2015 May 17

I'd like a source code inspector.

I wrote on 2015 March 12 about some extensions to javadoc-/doxygen-style annotation schemes, to explain how @location and @index tags could used to better document codebases.

Specifically, the problem I'm referring to is this: I get a link to a repo and am presented with a file tree and sometimes a README. The README is sometimes helpful, sometimes not. When I'm digging through the source tree in either case, what's not helpful is the three-column table presentation of $DIRECTORY_OR_FILE_NAME, $RECENT_COMMIT_MESSAGE, $RECENT_COMMIT_DATE, where the commit is the one that last changed that particular file/directory.

(Really, I have no idea why this is so prevalent in web-based version control frontends. It seems like it has to be a case of, "Well, this is just what these sorts of things always look like...", without regard for whether it's helpful or if it ever made any sense at all.)

What I'd like to see in its place is a one-liner for each entry in the file tree, to describe the source layout. This is harder to do for directories, which is why I proposed @location and @index.

@index + @fileoverview associates the annotations for the file containing them with the directory that the file appears in, in addition to the file itself.

@index + @location can be used if the file's @location annotation is a good way to describe the parent directory.

Uncombined @index with argtext of its own can be used where neither the file's own @location nor its @fileoverview are good candidates for describing the parent directory.

[For @index-as-a-modifier, it should either appear on the same line as the associated @location or @fileoverview tag, or it can appear on a line by itself, with no argtext of its own, in which case it modifies whatever tagspec preceded it.]

I'm also considering the idea of using a filename argument to the @index annotation, for deferring to some other file like so: @index README.markdown—where the README could contain a source layout section to describe things. E.g.:

== Source layout ==

@index README.markdown  
* foo/ - Short description of foo/ goes here...
* bar/ - Description of baz/
  * baz/ - likewise...

'@index.  ' could be used as shorthand, so repeating the name of the file isn't necessary, and would guard against file moves. Sophisticated markdown viewers could hide the tag and/or turn the directory labels into live links. NB: The two trailing spaces at the end when @index is used this way (i.e. inside a markdown file) MUST be included; the treatment of LF/CRLF in GitHub-flavored markdown is a sin.

[To distinguish between the argtext-as-description and argtext-as-delegate for @index, the rule would be "If it looks like a file name, then it's a file, otherwise it's freeform text". ("Looks like a file name" isn't as hard as it sounds; the contents of a given directory are knowable/known.)]