Changes between Initial Version and Version 1 of Ticket #2855, comment 6


Ignore:
Timestamp:
Jan 4, 2017, 11:21:41 PM (4 years ago)
Author:
Chris Johns
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • Ticket #2855, comment 6

    initial v1  
    99How a user uses the RSB or Eclipse is valid user documentation and it is not related to the kernel. Having this type of documentation in the unrelated kernel source repo would cause 2-way commit churn where user doc changes unrelated to the kernel would require buildbot rebuilds of the kernel and kernel changes would require documentation rebuilds.
    1010
    11 For me having the documentation source in the kernel source tree so a specific part of the documentation could be automatically updated is a questionable small gain at a larger cost. I question any formal user API documentation we have being automatically generated this way for a few reasons. It becomes difficult to audit changes because you need to de-reference the location in the documentation source to the location source tree and I feel formal user API interface should be fixed and cannot change without careful consideration rather then kernel source file changes. Second, we have more than one place documentation can be located which means more complexity in how we maintain the documentation, and finally we would need to find a suitable format for use because there is no tool I know of that can do a suitable doxygen type extraction to ReST.
     11For me having the documentation source in the kernel source tree so a specific part of the documentation could be automatically updated is a questionable small gain at a larger cost. I question any formal user API documentation we have being automatically generated this way for a few reasons. It becomes difficult to audit changes because you need to de-reference the location in the documentation source to the location in the kernel source tree and I feel formal user API interfaces should be fixed and cannot change without careful consideration rather than being seen as kernel source file changes. Second, we have more than one place documentation can be located which means more complexity in how we maintain the documentation, and finally we would need to find a suitable format for use because there is no tool I know of that can do a suitable doxygen type extraction to ReST.
    1212
    1313> 2. Move the BSP README files to the documentation directory into the CPU Supplement.
    1414
    15 I wonder if we should have a single document for BSPs and this be a chapter. I see not need for lots of separated manuals.
     15I wonder if we should have a single document for BSPs and this be a chapter. I do not see a need for lots of separated manuals.