[DOC] Missing completions-design.txt?

[DOC] Missing completions-design.txt?

[Brian Norris]

Hi,

It looks like Nicholas submitted this doc a while back as patch 2/2:

"[PATCH 2/2] doc: detailed documentation for completion"
http://lkml.iu.edu/hypermail/linux/kernel/1412.2/03676.html

where patch 1/2 got merged as this:

202799be447b doc: brief user documentation for completion

References in the introduced completion.txt doc have pointed lost souls
at an elusive completion-design.txt:

  "for details on completion design and implementation see
  completions-design.txt"

Since as we well know, most developers are religious readers of
documentation, presumably there are people out there waiting expectantly
for such a file to appear in their otherwise exhaustive Documentation/.
Can you help such lost souls out?

Thanks,
Brian

P.S. I haven't actually read the design doc that closely yet. Who would
trust such a random patch off the archives, after all? So just removing
the mention of this file might be a satisfactory solution.

Re: [DOC] Missing completions-design.txt?

[Nicholas Mc Guire]

On Tue, Oct 25, 2016 at 12:50:01PM -0700, Brian Norris wrote:
> Hi,
> 
> It looks like Nicholas submitted this doc a while back as patch 2/2:
> 
> "[PATCH 2/2] doc: detailed documentation for completion"
> http://lkml.iu.edu/hypermail/linux/kernel/1412.2/03676.html
> 
> where patch 1/2 got merged as this:
> 
> 202799be447b doc: brief user documentation for completion
> 
> References in the introduced completion.txt doc have pointed lost souls
> at an elusive completion-design.txt:
> 
>   "for details on completion design and implementation see
>   completions-design.txt"
> 
> Since as we well know, most developers are religious readers of
> documentation, presumably there are people out there waiting expectantly
> for such a file to appear in their otherwise exhaustive Documentation/.
> Can you help such lost souls out?
>
If I remember correctly it was Jonathan Corbet that suggested to merge the
two and atleast the usage part got merged in the current completion.txt 
The path descriptions were not included as it was not clear how long such
a path documentation would actually hold - so that was deliberately dropped
The design goals/rational was more or less lost or not seen as relevant here
as were the references/history and RT notes. As far as I remember it was a
deliberate decision to drop these parts as they were not seen to be necessary.

Those missing bits could be merged into the current completion.txt I do not
think it makes much sense to have it in a seperate file.

thx!
hofrat

[PATCH] docs/completion.txt: drop dangling reference to completions-design.txt

[Brian Norris]

Per the original author, the proposed document was never deemed
necessary, and the important bits got merged into completion.txt. Let's
just stop confusing readers by pointing at a nonexistent doc.

Signed-off-by: Brian Norris <briannorris@chromium.org>
---

On Wed, Oct 26, 2016 at 10:11:26AM +0000, Nicholas Mc Guire wrote:
> On Tue, Oct 25, 2016 at 12:50:01PM -0700, Brian Norris wrote:
> > References in the introduced completion.txt doc have pointed lost souls
> > at an elusive completion-design.txt:
> > 
> >   "for details on completion design and implementation see
> >   completions-design.txt"
[...]
> If I remember correctly it was Jonathan Corbet that suggested to merge the
> two and atleast the usage part got merged in the current completion.txt 
> The path descriptions were not included as it was not clear how long such
> a path documentation would actually hold - so that was deliberately dropped
> The design goals/rational was more or less lost or not seen as relevant here
> as were the references/history and RT notes. As far as I remember it was a
> deliberate decision to drop these parts as they were not seen to be necessary.
> 
> Those missing bits could be merged into the current completion.txt I do not
> think it makes much sense to have it in a seperate file.

I'm not super interested in the missing bits -- just in de-obfuscating
the doc. How about this?

 Documentation/scheduler/completion.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt
index 2622bc7a188b..656cf803c006 100644
--- a/Documentation/scheduler/completion.txt
+++ b/Documentation/scheduler/completion.txt
@@ -25,8 +25,7 @@ struct completion that tells the waiting threads of execution if they
 can continue safely.
 
 As completions are scheduling related, the code is found in
-kernel/sched/completion.c - for details on completion design and
-implementation see completions-design.txt
+kernel/sched/completion.c.
 
 
 Usage:
-- 
2.8.0.rc3.226.g39d4020

Re: [PATCH] docs/completion.txt: drop dangling reference to completions-design.txt

[Jonathan Corbet]

On Tue, 15 Nov 2016 14:42:14 -0800
Brian Norris <briannorris@chromium.org> wrote:

> Per the original author, the proposed document was never deemed
> necessary, and the important bits got merged into completion.txt. Let's
> just stop confusing readers by pointing at a nonexistent doc.

Makes sense, applied.

Thanks,

jon