You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
nom-tam-fits can be awfully intimidating and confusing to new users. One reason for that is that the library exposes too much of its internal workings in the public API, and also because it has grown organically over 25 years, retaining many dead-ends from earlier versions along the way. While we strive to maintain back compatibility as much as possible in the library itself, maybe we can trim the user documentation to focus on what users actually need; be more welcoming and helpful to new users. Specifically:
Hide packages and classes from the online API docs, which are meant for internal use only. (Contributors can still build the full API docs for their own use -- e.g. via mvn package).
Show only the public content in the online documentation. When using the library to read and/or write FITS files, there is no need to extend the classes of the library (with the exception of FitsHeaderImpl perhaps, whose methods are all public). Again contributors, who need the nuts and bolts, can easily build their own documentation using maven)
Mark the variables and methods meant for internal use only but which are nevertheless exposed to the public (or protected) API, as deprecated. In a future major revision (e.g. 2.0) we can hide these methods more effectively.
Eventually (after a year or 2) remove deprecated APIs from the online documentation, leaving only the recommended current API
The text was updated successfully, but these errors were encountered:
nom-tam-fits can be awfully intimidating and confusing to new users. One reason for that is that the library exposes too much of its internal workings in the public API, and also because it has grown organically over 25 years, retaining many dead-ends from earlier versions along the way. While we strive to maintain back compatibility as much as possible in the library itself, maybe we can trim the user documentation to focus on what users actually need; be more welcoming and helpful to new users. Specifically:
mvn package
).public
content in the online documentation. When using the library to read and/or write FITS files, there is no need to extend the classes of the library (with the exception ofFitsHeaderImpl
perhaps, whose methods are all public). Again contributors, who need the nuts and bolts, can easily build their own documentation using maven)The text was updated successfully, but these errors were encountered: