(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.)]