A tiny case study in why you shouldn't autogenerate documentation
-
Seatwave's API documentation has got some sweet autogeneration of descriptions going on. That
GetEventByID
method? It Gets the event by ID. TheGetUpdatedEvents
method? It Gets the updated events. TheGetEventsForEventGroup
method? It Gets the events for event group. Isn't documentation great and helpful?How about the
EventsSearch
method? Let's take a look at https://developer.seatwave.com/API/method/EventsSearch?apiName=discovery...Hmm.
-
Additional detail: it's been this way since I encountered the API in 2012. Apparently they've managed to survive for 6 years as a business but at no point has anybody on their dev team felt any need to fix this.
-
@cabbage said in A tiny case study in why you shouldn't autogenerate documentation:
Additional detail: it's been this way since I encountered the API in 2012. Apparently they've managed to survive for 6 years as a business but at no point has anybody on their dev team felt any need to fix this.
What's the fix? Rename the function
SearchEvents
? That would break everything that uses that function! Whargagablargh!
-
-
@tsaukpaetra said in A tiny case study in why you shouldn't autogenerate documentation:
What's the fix? Rename the function
SearchEvents
? That would break everything that uses that function! Whargagablargh!function EventsSearch(foo, bar) { /* Fix for faulty auto-generated documentation */ SearchEvents(foo, bar); }
-
-
@maciejasjmj - Yes, default auto-generation can be bad. A few modern tools are getting better are the "English", and are also providing tracking for which elements have been reviewed/accepted by a human.
Is this a thread a "Tiny Case Study on the Risks of AutoGenerated Documentation" DEFINATELY. But provided one is diligent, it can be a great way to get to an initial "alpha" starting point.
-
@thecpuwizard said in A tiny case study in why you shouldn't autogenerate documentation:
But provided one is diligent, it can be a great way to get to an initial "alpha" starting point.
I don't see the point. With no documentation, you provide zero information over what the signature can tell you. With autogenerated documentation, you provide zero information over what the signature can tell you.
-
Someone mandated that every function should be documented.
-
@maciejasjmj said in A tiny case study in why you shouldn't autogenerate documentation:
@thecpuwizard said in A tiny case study in why you shouldn't autogenerate documentation:
But provided one is diligent, it can be a great way to get to an initial "alpha" starting point.
I don't see the point. With no documentation, you provide zero information over what the signature can tell you. With autogenerated documentation, you provide zero information over what the signature can tell you.
With the better tools, it goes beyond what the signature will tell you (but clearly is still limited to what the "code" will tell you).
The bigger element is exposure (availability of the information). As comments before the method, there no real value, but process those comments into a rich hyper-linked "document" (or site or wiki or) and the value can be quite significant, especially with larger codebases, where it is quite common to not have all of the source code on your machine.
-
@maciejasjmj said in A tiny case study in why you shouldn't autogenerate documentation:
@thecpuwizard said in A tiny case study in why you shouldn't autogenerate documentation:
But provided one is diligent, it can be a great way to get to an initial "alpha" starting point.
I don't see the point. With no documentation, you provide zero information over what the signature can tell you. With autogenerated documentation, you provide zero information over what the signature can tell you.
He said it's a good starting point, and I agree. With many APIs many functions are self-explanatory anyways. I mean for, getEventByID(int id), I don't expect a novel, and if you do need a novel to explain stuff about this function, chances are your API is an utter failure. So, for those, auto-generation with an obvious description of the function and its arguments would suffice. Having someone spend tedious time manually constructing them is pointless.
And obviously if your API is a little more than a simple CRUD, you'll have certain functions that require a little more expansion and description. That's where you have a decent technical writer flesh that out.
-
@maciejasjmj said in A tiny case study in why you shouldn't autogenerate documentation:
@thecpuwizard said in A tiny case study in why you shouldn't autogenerate documentation:
But provided one is diligent, it can be a great way to get to an initial "alpha" starting point.
I don't see the point. With no documentation, you provide zero information over what the signature can tell you. With autogenerated documentation, you provide zero information over what the signature can tell you.
I see (poor) autogenerated documentation as a negative because now you will no longer get the "Missing XML comment for publicly visible type or member" warning.
-
@the_quiet_one said in A tiny case study in why you shouldn't autogenerate documentation:
He said it's a good starting point, and I agree. With many APIs many functions are self-explanatory anyways.
Then they don't need any documentation beyond the method signature. (Usually they do, though. What happens if your
getEventByID(int id)
receives an ID for a nonexistent event? Does it throw? Does it return null? Does it return a null object?)Autogenerated documentation is just deluding yourself into thinking you have documentation when in fact, you don't. It's not even that you have bad documentation, you have no documentation.
-
@maciejasjmj said in A tiny case study in why you shouldn't autogenerate documentation:
@the_quiet_one said in A tiny case study in why you shouldn't autogenerate documentation:
He said it's a good starting point, and I agree. With many APIs many functions are self-explanatory anyways.
Then they don't need any documentation beyond the method signature. (Usually they do, though. What happens if your
getEventByID(int id)
receives an ID for a nonexistent event? Does it throw? Does it return null? Does it return a null object?)Usually you're going to be consistent about basic CRUD operations, so the auto-generated documentation can just say what it does for each getByID. If you have CRUD operations for dozens of objects, do you really think it's a better thing to have someone just type out "This will throw if the ID doesn't exist?" over and over for each getByID function?
Autogenerated documentation is just deluding yourself into thinking you have documentation when in fact, you don't. It's not even that you have bad documentation, you have no documentation.
It only deludes you if you're delusional. I work for a group that actually thinks about things and knows the tools they use, not relying on auto-generation for things it's not designed for. You know, like pretty much every tool in existence, there are times using it is good, and times when it's not. You're making the usual fallacy that because stupid people might misuse a tool, it means the tool itself is bad.
-
@the_quiet_one said in A tiny case study in why you shouldn't autogenerate documentation:
@maciejasjmj said in A tiny case study in why you shouldn't autogenerate documentation:
@thecpuwizard said in A tiny case study in why you shouldn't autogenerate documentation:
But provided one is diligent, it can be a great way to get to an initial "alpha" starting point.
I don't see the point. With no documentation, you provide zero information over what the signature can tell you. With autogenerated documentation, you provide zero information over what the signature can tell you.
He said it's a good starting point, and I agree.
Thanks!
|With many APIs many functions are self-explanatory anyways. I mean for, getEventByID(int id), I don't expect a novel, and if you do need a novel to explain stuff about this function, chances are your API is an utter failure.
But is that self explanatory (from the signature I can not tell what will happen if you pas in an int which does not map to an Event) ????
-
@thecpuwizard Yeah, read further. @Maciejasjmj brings that up, and I address it.
-
If you can’t document anything nice...
-
/// Nices the documentation
-
I'm very much in favor of tools that don't generate any text in those tags. StyleCop analyzers may force some super-repetitive wording, but I find that that's as much help as I even want anyone to have writing comments. You have to actually think about what you're writing.
Too bad no one ever wants me to turn on Doxygen...
-
@the_quiet_one said in A tiny case study in why you shouldn't autogenerate documentation:
@thecpuwizard Yeah, read further. @Maciejasjmj brings that up, and I address it.
You traveled back to time and pre-posted me ;)
Again, that ignores the linking capabilities when the comments are processed, as well as the ability for generation documentation to examine the body of the code (and base classes, and the classes used as parameters, et. al.) to provide the information in a clear concise form.
-
What's eventses, precious?
https://nerdist.com/wp-content/uploads/2017/03/gollum-smeagol-singing.jpg
-
@jbert said in A tiny case study in why you shouldn't autogenerate documentation:
I see (poor) autogenerated documentation as a negative because now you will no longer get the "Missing XML comment for publicly visible type or member" warning.
Case in point: I worked for a project that decided (years and years ago) that all functions should be documented and thus tuned whatever build script they were using at that time to spew a warning for each undocumented function.
As a result, one smart-ass ran a script that added a documentation block to each function, which contained "UNDOCUMENTED" and nothing else.
And thus all functions became magically documented, no more warning were spewed, and the manager could happily claim that all the code was documented.
-
@remi said in A tiny case study in why you shouldn't autogenerate documentation:
@jbert said in A tiny case study in why you shouldn't autogenerate documentation:
I see (poor) autogenerated documentation as a negative because now you will no longer get the "Missing XML comment for publicly visible type or member" warning.
Case in point: I worked for a project that decided (years and years ago) that all functions should be documented and thus tuned whatever build script they were using at that time to spew a warning for each undocumented function.
As a result, one smart-ass ran a script that added a documentation block to each function, which contained "UNDOCUMENTED" and nothing else.
And thus all functions became magically documented, no more warning were spewed, and the manager could happily claim that all the code was documented.
Unfortunately not uncommon. This is why "Generation tooling" that can examine comments to see if they have been reviewed is so helpful.
-
@the_quiet_one said in A tiny case study in why you shouldn't autogenerate documentation:
do you really think it's a better thing to have someone just type out "This will throw if the ID doesn't exist?" over and over for each getByID function?
Hey, that's a use for cut-n-paste coding!
The awkward bit of documentation isn't “what does this function do” but “how do I use this function with the others”. It's very easy to have functions where their individual purposes are simple but the overall pattern is not.
-
Most of these stupid doc lines wouldn't be a problem if developers remembered that all function names must be verbs.
-
@thecpuwizard said in A tiny case study in why you shouldn't autogenerate documentation:
Unfortunately not uncommon. This is why "Generation tooling" that can examine comments to see if they have been reviewed is so helpful.
Don't worry, someone will run a script to review the whole code.