Mailinglist Archive: yast-devel (91 mails)

< Previous Next >
Re: [yast-devel] Drop *-devel-doc YaST subpackages?
Dne 5.1.2016 v 14:32 Lukas Ocilka napsal(a):
On 5.1.2016 14:10, Ladislav Slezak wrote:
[...]
- Does anybody actually use them? IIRC I have never used any devel-doc
package,
if I need a documentation for a function I usually check the source code or
grep
the YaST code for example usages.

The question is: Who excluding Yast developers use them? The answer is: We do
not
know, but we should still think about use-cases for the docs first.

The *-devel-doc packages are designed for developers mainly so there should be
just
few people who are not YaST core developers and use them... And as the YaST
community
is tiny I'm almost sure that the set of the users is empty... :-(

Although this is true, devel-doc packages are tight to actual packages on the
system. Different API, different documentation.

Rubydoc.info supports also branches, you can generate the doc for any branch
(or even
a commit), e.g. the SLE12-GA documentation is available here:
http://www.rubydoc.info/github/yast/yast-ruby-bindings/SLE-12-GA/index
the SLE12-SP1 is here:
http://www.rubydoc.info/github/yast/yast-ruby-bindings/SLE-12-SP1/index
...etc


IMO many people do not know WHERE to find the documentation and local system
is
the first place to check.

Um, in this case it's not that trivial as it might seem. The devel-doc packages
are not installed by default, you have to search the packages first. Then
install it,
list it's content to see what's actually there, start the browser and
load the documentation... Even the current situation is not good enough.

- When I want to point someone to a function then I usually post a link to
the
GitHub sources or to a RubyDoc.info rendered doc (like [2]).

Yes, that is good for people that ask for something. But if you have to find
it
yourself, then it's not so easy.

We could add links to the main README.md files...

- If you really need a local documentation you can always run yardoc manually
(via `make doc`/`rake yard`).

Which is a fair point - but we should still have this info in
/usr/share/doc/packages/ for each package (README.md, DOCUMENTATION.txt ...),
moreover with links to the online docs.

Yes, as mentioned above.

yast2-pkg-bindings-devel-doc (this is for a C++ package, maybe it still makes
sense...)

Depends on the use-case.

The point here is that this is a C++ code. Obviously rubydoc.info cannot
process it
and publish the generated doc.



--

Ladislav Slezák
Appliance department / YaST Developer
Lihovarská 1060/12
190 00 Prague 9 / Czech Republic
tel: +420 284 028 960
lslezak@xxxxxxxx
SUSE
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
To contact the owner, e-mail: yast-devel+owner@xxxxxxxxxxxx

< Previous Next >