https://bugs.documentfoundation.org/show_bug.cgi?id=148621
Bug ID: 148621
Summary: The horrible state of the BASIC API and documentation
Product: LibreOffice
Version: unspecified
Hardware: All
OS: All
Status: UNCONFIRMED
Severity: normal
Priority: medium
Component: BASIC
Assignee: [email protected]
Reporter: [email protected]
Created attachment 179607
--> https://bugs.documentfoundation.org/attachment.cgi?id=179607&action=edit
Poor documentation layout
Preface: I've been a web developer for over 15 years. I've read API docs from
hundreds, possibly over a thousand of libraries and projects. LibreOffice is
the most horribly organized API that I've seen, with the worst documentation
that I've encountered. I'm really sorry to say this, but it's my honest
opinion.
To make this bug more concrete and actionable, I'll give some examples.
1. Five years since I've asked, there is still no clear reference documentation
for the JavaScript macro API
(https://ask.libreoffice.org/t/javascript-macro-reference/25851). Why does it
even exist?
2. The documentation web page template at
https://help.libreoffice.org/7.4/en-US/text/sbasic/shared/03/lib_tools.html has
a pointlessly narrow column width, which truncates the visible text and makes
it impossible to clearly see an entry at once (see screenshot). That text
column also scrolls through the search bar at the top.
3. Searching through the macros documentation returns a jumble of results,
mixing user-facing functions and Calc formulas. Try searching for "regular
expression" in hopes of finding a BASIC macro function that does regular
expression search and replace. Apparently there isn't one. 🤦
To use regular expressions, you need to import some cryptic service, and the
code looks like this mess: 🤢
yourString = 'Some string with a cell reference like A123 and other stuff'
oTextSearch = CreateUnoService("com.sun.star.util.TextSearch")
oOptions = CreateUnoStruct("com.sun.star.util.SearchOptions")
oOptions.algorithmType = com.sun.star.util.SearchAlgorithms.REGEXP
oOptions.searchString = "([A-Z0-9]+)"
oTextSearch.setOptions(oOptions)
oFound = oTextSearch.searchForward(yourString, 0, Len(yourString))
sFound = mid(yourString, oFound.startOffset(0) + 1, oFound.endOffset(0) -
oFound.startOffset(0))
MsgBox(sFound)
(By the way, I found this on StackOverflow, not anywhere in the documentation.
For 20+ years, the vast majority of programming languages have had built-in
functions for regular expression search.)
4. The BASIC **Strings** module
(https://help.libreoffice.org/7.4/en-US/text/sbasic/shared/03/lib_tools.html?&DbPAR=BASIC&System=UNIX#strings_module)
lacks such basic functions as finding or replacing based on regular
expressions. 🤦🏼♂️ Instead, it provides a **Power** function, which has
absolutely
nothing to do with strings, or a "CheckDouble" one, without documentation.
5. Apparently nobody has edited the documentation for comprehensible English.
>From the same page: "Retrieves the second value for a next to 'SearchString' in
a two-dimensional string-Array" - what?
6. The documentation is apparently split up with some parts at
help.libreoffice.org, and others at api.libreoffice.org (e.g.
https://api.libreoffice.org/docs/idl/ref/servicecom_1_1sun_1_1star_1_1util_1_1SearchDescriptor.html,
which again is devoid of examples and context)
I know there are probably historical arguments for why things are the way they
are, but please understand that A NEW DEVELOPER DOESN'T CARE about this, and
they will be turned off by the current state of the API and documentation. (I'm
weird and have stuck with it for 5+ years, but for every person like me, 100
have just left without bothering to leave any feedback - see
https://en.wikipedia.org/wiki/1%25_rule).
So if we want to stop scaring away users and macro developers, we'd better fix
this.
--
You are receiving this mail because:
You are the assignee for the bug.
